Comments on: Clarifying the Document Structure

Comments on: Clarifying the Document Structure

I wanted to clarify the structure of the new REBOL 3 Documentation. Since it currently consists of more than 740 pages, it's good to understand why it is structured in a specific way.

I've written this document, Document Structure and Objectives, to provide a permanent explanation of the document's objectives and design.

First, I will admit that I was influenced by the Apple OS X manuals. I've found them to be helpful, generally well written and structured. So, I wanted to model the the new doc system in a similar way (although our docs are certainly not of the OS X magnitude.)

As I've noted before, I also like the sidebar navigation. We had it in our first manual, then we removed it for some long forgotten reason. We don't have it yet on the new docs, but you can expect to see it soon. We'd also like to add a hide button for it, in case you find it distracting or want to print the page.

And finally, I should note again that this is a huge document... and it takes incredible amounts of time and energy to deal with it. There are still many missing pieces and older sections that need editing. You will need to either be patient as things progress, or step forward and help the project move forward. Thanks.

6 Comments

Comments:

Luis.
25-Feb-2009 1:29:50 Hiya,
On the 'Document Structure and Objectives' page I noticed an error:
'This page outlines the our organizational objectives'
Should be:
'This page outlines our organizational objectives'.
There's nothing quite like starting on the wrong foot.. :P
Cheers,
Luis.
Henrik
26-Feb-2009 9:20:07 There's nothing quite like starting on the wrong foot.. :P
Which makes it fortunate that it's a Wiki. :-) Typos are fixed.
Jos'h
26-Feb-2009 14:14:33 If you haven't already considered it, you could just hide the sidebar with a CSS print stylesheet instead of having to provide explicit controls for it.
Wilfred
26-Feb-2009 14:21:42 Steve Gibson, Gibson Research Co, has developed a neat CSS masthead navigation menu:
www.grc.com/menu2/invitro.htm
Features: Absolute browser and platform compatibility: Text scaling friendly Narrow window width handling Functional for non-CSS, or CSS-disabled, browsers No client-side scripting
If need be, it might be adapted to a sidebar style.
Wilfred
26-Feb-2009 14:29:26 There is also Stu Nicholls excellent site at: http://www.cssplay.co.uk/menus/final_drop.html where, it seems, a great deal of css menu development may have been done.
Michael
1-Mar-2009 5:41:09 I have been waiting impatiently for R3 but now I am really more interested in the documentation approach and when it will be shared. It addresses some common problems that are not totally solved by wiki usage at my job site.

Comments on: Clarifying the Document Structure

Comments:

Post a Comment: