[Grok-dev] feedback on the Grok site

[Kevin Teague]

>
> 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.
>

Yes, the documentation navigation is currently optimized for a site  
that has much more documentation (e.g. each sub-link would lead to a  
large list of documents). This problem will fix itself eventually,  
although it could take a few years ...

... however, creating a new View into the documentation section that  
pulls together all the docs into one page isn't too hard to do, and  
would be helpful.

Note that the Documentation section is using Plone Help Center which  
already has a feature for listing all docs - but it's targeted at  
content managers, we would just need to make a similar view tweaked  
for end users (see http://grok.zope.org/documentation/stats and just  
hit "search" at the bottom of the page).

> 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?
>

Yes, I agree that there is room for improvement in the site  
navigation. The Grok site in it's current form is fairly newly minted  
so there are still lots of areas of improvement where there is low  
hanging fruit.

> 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!
>

Yes, this is bothersome. The rest of the site has the main navigation  
in the left column, but repeating this in the documentation area adds  
extra cluter. Fixing this is a matter of prototyping some static HTML  
designs with a top global navigation bar, getting more people to like  
it than dislike it, doing some cross-browser testing, and then finally  
updating the site theme and deploying.

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

This is the easiest to fix (at least if you've got knowledge of Plone  
3 dev and Plone Help Center), and is the most likely task that I may  
get around to doing something about in the not too distant future.

> * 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.

There is some work done on Grok off-line docs (which will contain the  
Grok Tutorial and Grok Reference) that use a layout that uses the left  
column for table of contents. I think we will initially host these  
docs statically within /documentation/ somewhere (easy to do but docs  
won't show up in local site searches) and eventually sync or index the  
contents in the site search (requires a fair bit of work). However,  
creating a portlet for the left column within the dynamic  
documentation that mimics the static layout might work. Many of the  
documents are in the PHC HowTo content-type, which doesn't have any  
notion of structure - although this could be implied from headers. For  
the content that is in the PHC Tutorial content-type it's already  
strucutred into sections, so a table-of-contents style navigation  
would be easy to do, and think be quite nice.

... as for when all this work will be done, I've only been doing  
"small trickles" of work on Grok recently. Eventually I'll get the  
itch to do a round of more significant improvements to the site, but  
in the meantime, if anyone wants to contribute I am willing to help  
out with guidance/deployment on getting a development sandbox of the  
grok site running where changes can be made before going live. We have  
a development buildout for the site (http://svn.zope.org/grok/website/buildouts/development/ 
)  (this does require Plone 3 knowledge). Other contributions such as  
prototypes of changes in the form of static HTML, or just general  
suggestions are of course still welcome.

We should also have a place for collecting all the issues surrounding  
the Grok web site - right now we've just got the mailing list and  
there are about a kajillion Grok web site TO-DO lists floating around  
in different places on the net. The Grok bug tracker on launchpad is  
probably not quite the right place, since I think the tracker is  
fairly project-centric and those issues are focued on Grok itself.  
Perhaps another project called "Grok web site" on launchpad, or we  
just use another issues tracker (Trac, Roundup, JIRA, Poi, etc.  
etc.) ... of course, Grok isn't a *real* web framework until someone  
writes a bug tracker with it :)