7. and <nowiki>.
<h1>Documentation outline</h1>
The documentation for fossil needs to be divided into these main sections:
* <cite>[Tutorial]</cite>
* <cite>[Cookbook]</cite>
* <cite>[Reference]</cite>
* <cite>[Developer Guide]</cite>
<h2>Tutorial</h2>
The tutorial portion is the hand-holding portion that takes a new user through
the steps of getting, building and using fossil. Fossil's terms should be
defined here and basic workflow established. Ideally a sample project should
be used to show fossil in use and give the user something to type to magically
have fossil do cool stuff.
<h2>Cookbook</h2>
The cookbook is a task-oriented portion (likely one that's ever-expanding as
fossil is increasingly developed and honed) designed for a user who has basic
skills in using fossil (like, say, me) but isn't familiar with all the fancier
aspects of it and the inobvious workflows that it supports. Each "recipe" (use
case) in the cookbook should follow a format with these following points:
* Succinct problem statement.
* Detailed statement of problem and motivation for solution.
* Detailed instructions (<em>no discussion!</em>) for implementing the solution.
* Discussion of the solution including, if applicable, pitfalls and
alternatives.
<h2>Reference</h2>
The reference is self-explanatory. Basically take everything from <code>fossil
help *</code> and put it here. However, the terseness of <code>fossil
help</code>, while good for a quick reminder at the command line, is not
suitable for "real" documentation. Ideally each documented element in the
reference should have a full explanation, including links to related items, as
well as <em>examples</em>. (This has been what's killing me with grokking some
aspects of fossil: I just can't figure out what they do!)
<h2>Developer Guide</h2>
It is inevitable that people will want to start building third-party tools that
interface with fossil as fossil gets more widely adopted and more mature. We
might as well head off the inevitable and let developers have the information
they need without tearing apart the source to get to it. This would include
things like:
* any APIs it would be reasonable to expose
* a current, up-to-date database schema
* notes on inner workings (already supplied, but might need dusting off and
TLC)
* anything else we can think of (Lua/Tcl/whatever bindings?)