Documentation outline

Documentation outline

The documentation for fossil needs to be divided into these main sections:


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.


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:


The reference is self-explanatory. Basically take everything from fossil help * and put it here. However, the terseness of fossil help, 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 examples. (This has been what's killing me with grokking some aspects of fossil: I just can't figure out what they do!)

Developer Guide

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: