[Grok-dev] two notes about documentation

[Brandon Craig Rhodes]

Since it seems to be a week of comments about the online docs at
grok.zope.org, I have to questions:

   - On the home page, the words in the orange box, "all about",
     "download", and "learn", are smaller than the text around them.
     The style sheet should be adjusted to make them the same size.
     They look silly smaller.  The designers should look all over the
     site while using Firefox + and - to change the font size, and make
     sure all of the fonts scale together.

   - On all of the howto pages, the little "description" paragraph at
     the top is impossible to visually distinguish from the rest of the
     text.  It doesn't even benefit from the space put between normal
     paragraphs!  I just runs against the paragraph below it.  It should
     probably be block-quote-looking with wider margins, and maybe
     italicized or something.

   - I still think we should stop hiding our document titles one level
     deep.  It's bad design to show the user a bunch of categories and
     assume that they'll know where they need to go without seeing any
     actual document titles below them.  I would just make the
     documentation page so that it shows the titles of all of our
     documents so that people can browse them without having to click
     twenty or thirty times like they have to right now.

     In the absence of any agreement that the navigation is bad and an
     obstacle to people who want to try out or use Grok - since I know
     there are people who really like putting the actual document titles
     one or more levels deep - could we keep the navigation there for
     the navigation-people, but have an "all documetnation on one page"
     link where people like me could click through past the navigation
     page and see a list of all docs on one page, maybe grouped by
     category, but with their titles all there?  Then those of us who
     want to see what's available without visiting a dozen pages could
     do so.

-- 
Brandon Craig Rhodes   brandon at rhodesmill.org   http://rhodesmill.org/brandon