[Grok-dev] feedback on the Grok site
kevin at bud.ca
Tue Mar 18 23:40:33 EDT 2008
> 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
> 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
> 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 :)
More information about the Grok-dev