Concerning the actual contents of a documentation system, I suppose a
framework might be composed of templates for:

1. Command syntax quick reference - fossil help ?cmd?
2. Command detailed reference
3. Cookbook-like containing "recipes" for various scenarios
4. Overview
  4a. System introduction - purpose, requirements, various metrics
  4b. Conventions, organization
5. Tutorials - user, maintainer, developer

An item 2 template might be structured like this:

> Relevant Definitions
> Description
> Example
> Explanation
> Rationale

Where the Examples might be excerpts from various Cookbook recipes (with
meta-data defining any dependency relations to source code and/or other
parts of the documentation).

Templates for the metrics of 4a could get interesting (possibly tying
into a test suite and/or incorporating user statistics). The idea is to
provide system engineers with relevant data and quantified decision
points upfront.

Item 5 is tricky. Would there need to be an underlying/intermediate
knowledge-base or would it be sufficient to have direct dependency
relations to the source?
fossil-users mailing list

Reply via email to