Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Artifact ID:	f723d122442b204fc73734adfe27e9e5adc8573d
Page Name:	Documentation outline
Date:	2008-05-24 15:42:23
Original User:	ttmrichter
Parent:	9432e8aba2747f051e62a6ca5c3fb30fe8427296 (diff)

Documentation outline

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

• Tutorial
• Cookbook
• Reference
• Developer Guide

Tutorial

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.

Cookbook

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 (no discussion!) for implementing the solution.
• Discussion of the solution including, if applicable, pitfalls and alternatives.

Reference

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:

• 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?)