Re: V2 documentation format: a resolution?

From: David Abrahams (dave_at_[hidden])
Date: 2004-02-11 10:27:29

Zbynek Winkler <zwin_at_[hidden]> writes:

> Vladimir Prus wrote:
>> I think V2 doc style is close to be finished now. It's at 
>> 
>> http://zigzag.lvk.cs.msu.su/~ghost/Boost.Build.docs2/
>> 
>> and we'll appreciate all comments. And it does not use neither background 
>> image, not gradient background ;-)
>
> 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. As I understood this would be the only documentation on Boost.Build2 
> so it probably should not be called User Manual either. 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. 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.
>
> Zbynek
>
> PS. 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).

I also like the idea of side-bound TOCs.

Also, no offense but the placement of Nav buttons is awful UI design.
To jump back and forth between two pages I have to move my mouse all
the way across the screen. They should be clustered together.

-- 
Dave Abrahams
Boost Consulting
www.boost-consulting.com