Dynamic Documentation

Problem

Out-of-the-box version gets customized for client projects, both by us and clients.

Solution

Document application’s building blocks and re-generate the documentation after the application is restructured.


Details

For more information on customizing earthcape application check out this documentation article.

We decided to use the customization capabilities to actually help make user documentation more USER friendly. In a nutshell, documentation will be provided for default configuration and users can re-generate documentation after the application is customized.

Topics contents can be edited and documents can be regenerated based on user’s own configuration of views, navigation and specified behavior (e.g. user defined validation rules) to include screenshots that contain data from own projects.

Documents are generated in markdown and can be merged with the bulk of shipped documentation and DevExpress modules reference to create a full user manual completely matching project setup.

Markdown source will also be shipped along side the compiled web site and PDF file. Source includes a docfx.json file and you can use DocFX and wkhtmltopdf to convert this file from a set of topics to an HTML website or a PDF file.

How this works

Application model is pre-loaded with topic contents based on the application nodes. E.g. Unit object will contain this description:

When the documentation is generated, these contents are generated from the model:

  • Description
  • Screenshots from currently opened database
  • Fields metadata (incl. their descriptions from Application Model)
  • Available views and their configuration
  • Table of contents corresponding to application navigation structure

Users are able to change the descriptions and views configuration, just like any other properties of model nodes, and re-generate the documentation locally.

This is is just a first attempt at this approach and it will evolve along with EarthCape application. So far, only EarthCape Windows Client model and screenshots are used for documentation generation.

Next steps will include:

  • make a push to add descriptions to most important model nodes
  • optimize the structure of the documentation
  • include web version documentation
  • include menu and toolbar commands

Current version of documentation based on default configuration and example database (based on heliconius.ecdb.io) is available here:

earthcape.com/docs

Menu