Re: WANTED: Design for documentation (Photoshop power users!)

[Robin Bannister]

I like the comprehensive navigation of the new layout [1], 
but feel there is still something missing. 
______________________________________________________________________

 Say I am reading the mailing list, looking at a thread or message. 
 I see something which gets me thinking about a problem I have, 
 and I follow a link there which takes me into the documentation. 
 
 There is something useful to read, and I may navigate around a bit, 
 looking for something even more relevant. I feel safe doing this 
 because the TOC panel shows me not only the breadcrumbs [3] in bold, 
 but also the lie of the land, providing a sort of peripheral vision. 
 
 I click on another link and go on reading, still thinking mainly about 
 my problem. And then I notice that I'm not so sure where I am, 
 even though the nice TOC panel is still there. 
 
 I would like to reread  a section that I read just after coming in. 
 I can remember its title, more or less. But I can't find it anywhere. 

______________________________________________________________________

This would not happen to an experienced reader, who
- recognises LM/NR/IR by page layout and treatment style 
- notices how links are grouped LM/NR/IR-wise 
and therefore has no trouble tracking movements across LM/NR/IR boundaries. 

But for the inexperienced reader, thinking about something else, these 
indications are too subtle. 

At first I thought, each document is a room (in the documentation house), 
and something in the rooms could be coloured as a key, 
e.g. LM green, NR blue, IR red, (to follow a famous example). 
This does let you notice the boundaries, but it is not explicit, 
and so could confuse and frustrate. 


So I propose

A   
Replace the (passive) text "Table of Contents" in the TOC panel, 
with the document title, e.g. "Learning Manual". 
This nearly always visible (on biggish screens). 
(And when offscreen, near the end of NR, it is not far away.) 


And to follow this up with additional suggestions: 

B   
Make this document title [A] be like a breadcrumb at the document level 
i.e. it is a link to the start of the document. 

C   
All documents have their document title headlined on the first page. 
(Only LM has this sort of title at the moment.) 

D   
When you follow the link [B] (or <Top>) you immediately see this title [C].
This reassures those who are getting disoriented. 

E   
Just above [B], add a (smallish) link called "Documentation", 
which goes to "higher than top" [2] [3]. 

F   
Because [E] is in the (extended) TOC panel, this link need not be provided 
as a button in the main pane. 
This provides another type of reassurance: 
- the main pane buttons never take you outside the document. 
And "Top" does not become ambiguous: it means only "Top of document". 


[1] http://kainhofer.com/~lilypond/Documentation/index.html
[2] http://lists.gnu.org/archive/html/lilypond-user/2008-07/msg00485.html
[3] http://lists.gnu.org/archive/html/lilypond-user/2008-09/msg00715.html


Cheers,
Robin