[Grok-dev] two notes about documentation
Brandon Craig Rhodes
brandon at rhodesmill.org
Fri Jun 6 11:59:29 EDT 2008
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
Brandon Craig Rhodes brandon at rhodesmill.org http://rhodesmill.org/brandon
More information about the Grok-dev