Re: V2 documentation format: a resolution?

From: Zbynek Winkler (zwin_at_[hidden])
Date: 2004-02-09 05:33:15

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).

PS2. 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). 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?

-- 
http://zw.matfyz.cz/ http://robotika.cz/
Faculty of Mathematics and Physics, Charles University, Prague, Czech Republic