Re: V2 documentation format: a resolution?

From: Christopher Currie (Christopher_at_[hidden])
Date: 2004-02-09 10:43:21

Zbynek,

A lot of your comments I agree with; some of them are specific to 
Boost.Build's docs, and others are more globally applicable to all 
BoostBook documentation; I'll address the Boost.Build ones here and 
direct you to the boost-docs list for the others.

> As I understood this would be the only documentation on Boost.Build2 
> so it probably should not be called User Manual either.

Do you have a suggestion for a better name? Volodya has commented that 
he thought that a "developer's manual" should be a separate document, so 
if we broke those bits out would it be better?

> I can't help it, I find it to look too "computer generated" ;-) It is 
> missing a human touch ;-) It looks like latex2html generated so it also shares 
> its drawbacks. For example the arbitrary nesting: looking at the 
> http://zigzag.lvk.cs.msu.su/~ghost/Boost.Build.docs2/bbv2.tutorial.hierarchy.html 
> I cannot tell where I am in the document except looking at the url or jumping 
> to the main toc (but that also does not help much).

There are several factors at work here. I think that some of the 
*information* within the Boost.Build docs need to be reorganized. The 
nesting is not arbitrary; it was based on the level of the header tags 
in the original document (<h2> became a chapter, <h3> a first-level 
section, etc.).

There are probably some places where the flow of the documentation could 
be improved by reworking where the section breaks are. The XML sources 
are in v2/doc/src; the tutorual.xml file particularly has been cleaned 
up enough to be readable to the Docbook uninitiated. Patches are welcome.

As for looking 'computer generated,' we welcome your help over on the 
boost-docs list to make ALL of boost's documentation look more 
professional. Information about the list is at:

http://lists.sourceforge.net/lists/listinfo/boost-docs

I'll make a few comments about the suggestions below on that list.

Christopher

> My personal preference 
> is to add margins to the sides so the text does not run all the way from one 
> border of the window to the other.

> the huge green 
> navbar at the top. It totally does not fit in with the rest of the document. 
> IMHO a navbar to be at each page have to be nonintrusive (small, not much 
> colors) and usefull (something that you really need at each page) and it 
> should have at least similar design as the rest of the document.

> I do not think it is a good idea to start with such a huge toc. Maybe a mix of 
> condensed version and/or synopsis and/or "how to use this document" would be 
> better.

> Also the local tocs kind of stand in the way of reading. I like them more 
> out of the way (ie. on the right side where I've put them in my php version of 
> the manual).

> Maybe it should have less 
> separate files? Or maybe some top navbar that would highlight at least the 
> chapter I am in? Maybe some "bread crumbs" navigation?