[Grok-dev] feedback on the Grok site

Brad Allen brad at allendev.com
Tue Mar 18 19:19:15 EDT 2008

Dear Mr. Grok,

Based on my own mistaken initial impression of sparsity of 
documentation on your Grok site, I'd like to offer some feedback:

The main documentation page currently fails to convey the extent of 
documentation available for Grok; casual browsers may get a false 
impression of sparse documentation.


The Grok documentation page only shows a few basic categories, and 
fails to advertise the wealth of documentation currently available.

Another problem is that most of the links on from the main 
documentation page don't lead directly to documentation, but instead 
each leads to another links page. Many of the "sub-links" pages only 
list one item. Once again, the casual browser may get the impression 
of content lacking, or at least may be frustrated from having to do 
too many levels of digging to navigate.

By contrast, check out the rich table of contents shown on Django's 
documentation page (see http://www.djangoproject.com/documentation/ 
), which advertises clearly the rich documentation available.

Overall, Django's site layout is a good example of a convenient, 
reader-friendly, easily navigable design; does anyone else agree with 
me that Grok's site could benefit greatly from a similar layout?

Here is what I propose for the Grok site:

* Add nav links running across the top. Currently this is missing, 
and when the user enters the documentation page, there are no links 
leading to other sections of the site!

* Main documentation page would look more like a table of contents 
contain direct links to doc pages.

* Each doc page would have an internal table of contents in the 
sidebar. This would replace what currently appears in the sidebar; 
the user would need to return to the main documentation page to get 
the main table of contents for documentation.

More information about the Grok-dev mailing list