Re: [jamboost] Re: V2 documentation format: a resolution?

From: Rene Rivera (grafik.list_at_[hidden])
Date: 2004-02-09 11:40:57

Reece Dunn wrote:

> Zbynek Winkler wrote:
> 
>>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.
> 
> 
> If there is a consensus on this, I'll have a look into this, but can't 
> promise anything!

A detailed TOC at the start of a book is somewhat standard. It gives one the 
opportunity to see all that is included in the text. For online docs it also 
gives the opportunity to briefly search for some specific topic you are 
interested in, and go there directly. But having the TOC at each page is 
distracting and superfluous. I would recommend, and prefer, having only one 
detailed TOC.

>>And last (but not least) - 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 like the one I did for the "Getting Started" docs: 
http://www.boost.org/more/getting_started.html

> I have been working on getting navlinks at the top (which will be available 
> when they get checked in). There was a few comments about retaining some of 
> the original look & feel, so I tried to keep the top as close to the 
> original as I could.

About the navbar...

The navbar is less than understandable as it stands. What does "Home" and "Up" 
mean? Those terms don't tie in to any other page I can see. If one of those 
refers to going to the TOC, then the link should say "TOC". OK, I looked at 
the links themselves, both point to the same location, so why have both? 
Having the links be images with the words in them is pointless. Having either 
a non-text image and a text label, or just having a text link is better. My 
ideal would be to put a TOC link on the top navbox only. And create a top and 
bottom navbar with previous, current, and next indicators/links. For example:

Chapter 1. How to use... ---- Chapter 2. Installation ---- Chapter 3. Tutorial
(in which only chapter 1 and chapter 2 are links... and no images)

This gives you the navigation, and an immediate frame of reference for what 
the links mean with regards to your current context.

PS. Now I looked at the Up vs. Home on the regular Boost docs and they are 
different. I would still move both of those to a topbox only, with appropriate 
names for the links to the sections they will take you to (instead of the 
generic terms).

About headings...

The coloring on chapter headings and sections is distracting. The more 
natural, from a typographical point of view, is to left-justify the headers, 
and follow them with indented body text. The headers are already different 
enough from the rest of the text to not really need more highlighting.

Overall structure...

I would really prefer to just have one page per chapter. It makes for much 
easier reading to just scroll down the logical sequence of the text, as 
opposed to having to flip back and forth through pages of closely related text.

Hmm, I see this is only a problem with the standalone version of the 
Boost.Build docs. The regular Boost docs put all the sections of a chapter 
together in one page.

...To summarize, the current L&F has the style of email communications, not 
book communication.

-- 
-- Grafik - Don't Assume Anything
-- Redshift Software, Inc. - http://redshift-software.com
-- rrivera/acm.org - grafik/redshift-software.com - 102708583/icq