Structured documentation that is easy to generate, synchronize and find.
As applications get bigger, having some technical documentation helps. Writing documentation for a big applications is hard work, so it’s not a surprise that most applications have none.
When the documentation is finally written, it’s typically not available to the end-users, or at least is easy enough for them to use it.
Moreover, as the application changes, the documentation gets outdated, users don’t trust it anymore, and they turn back to use informal mechanisms to learn.
With Help module we try to address or minimize this issues:
The documentation is written in a wiki, so it’s easier to modify by anyone (with permission).
The generated documents use a variant of wiki-markup and are stored in the database, but can be exported to XML files, so they are easy to move from one environment to other.
Each piece of documentation can be written in their exact place:
All this pieces of information can be linked, so we can, for example, make a link in the namespace introduction text to some of the entities.
By structuring the documentation the same way as the entities, way we get important benefits, let's see:
Simple one-line descriptions can be automatically created from the entities, giving the user information about the property type and implementations, entity live cycle or what database columns are shown on each query column. This automatic descriptions are localized and generated in real-time when the user access the help, without polluting the xml files.
The help module is able to synchronize the documentation as we make changes in the entities. As the schema synchronizer, is able to understand renames, changing or renaming the files. It also updates the links to other entities, properties, namespaces, etc..!
Since all the information is in the right place, is easy to show small help icon in the user interface to show help information.
Once in help mode, just by hovering over any type, property, operation, column, etc... a quick popover shows the automatic descriptions and any the manually redacted information associated. Just click in the element to open the web page with the full documentation or edit it.
Turn back to Signum Extensions