Friday, September 25, 2009

Working bits and pieces of the Neurospaces / GENESIS documentation system

The Neurospaces / GENESIS 3 documentation system consists of a flat set of simple documents that are hyperlinked together. The main entry point into the documentation can be found here. The basic outline of the structure of the documentation can be found here. Most of the documentation is structured according to the GENESIS user workflow, a simple description of operations that a user executes when he simulates a model.

Today we had some fun identifying more flows through the documentation. As such there are vertical flows that go into depth, and horizontal flows that give an overview of concepts or technology. There is also a 'related pages' flow and a hierarchical flow (also known by software engineers as 'breadcrumbs').

The GENESIS documentation system has a convenient tagging system to implement all these flows. For example, the content page for level 1 documentation (high-level overviews), lists all published documents that have the named tag 'level1'. All the pages that are related to the model-container (allows for efficient internal storage of models), are tagged with 'related-model-container'. This makes it easy to identify and name different flows through the documentation and link those documents in a dynamically way using tools that understand the tags and create the appropriate HTML just-in-time.

By design, the documentation system also allows to tag and describe pages and documents that are not directly under our own control. For example, we can tag and link to scientific publications on other websites, or to documentation of software that is not maintained by us.

Anyway, as you can imagine, working on such a system is a lot of fun, especially with this team, and especially when everything starts to work...

No comments: