Help

Structured documentation that is easy to generate, synchronize and find.

Documentation is hard

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:

Wiki-markup 

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.

Structured documentation

Each piece of documentation can be written in their exact place:

• Appendix: Unstructured documentation, typically for cross-cutting concerns that do not belong to a particular module (e.g., Installation, Server architecture…)
• Namespace: The namespaces of the application serve us a an index. On the namespace page we can write a semi-structured introductory article that presents the entities and their relationships (e.g., Accounting, Human Resources...)
• Entities: Each entity type has a page where we can write an entity description (e.g., Customer, Product, Task...).
  • Properties: If necessary, a block of information can be associated to a property (e.g., SubTotalPrice, ExternalId…).
• Operations: If necessary, a block of information can be associated to an Operation (e.g., Authorize Payment, Delete User..).
• Queries: If necessary, a description of the query can be written (e.g., Invoices ready to pay are the invoices that...)
  • Columns: Additionally, you can even put a piece of documentation describing a query column (e.g., Customer Fidelity Index…)

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: 

Automatic descriptions

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.

Synchronizing documentation

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..!

Integrated help

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.