Comments on: Clarifying the Document Structure
REBOL Technologies

Comments on: Clarifying the Document Structure

Carl Sassenrath, CTO
REBOL Technologies
24-Feb-2009 18:43 GMT

Article #0393
Main page || Index || Prior Article [0392] || Next Article [0394] || 6 Comments || Send feedback

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.

Post a Comment:

You can post a comment here. Keep it on-topic.

Name:

Blog id:

CS-0393


Comment:


 Note: HTML tags allowed for: b i u li ol ul font p br pre tt blockquote
 
 

This is a technical blog related to the above topic. We reserve the right to remove comments that are off-topic, irrelevant links, advertisements, spams, personal attacks, politics, religion, etc.

Updated 24-Nov-2017   -   Copyright Carl Sassenrath   -   WWW.REBOL.COM   -   Edit   -   Blogger Source Code