[Grok-dev] Rules of Grok document; how to integrate this into the website?

Kevin Teague kevin at bud.ca
Tue Apr 22 20:16:18 EDT 2008

Martijn Faassen-2 wrote:
> For now I've checked this document into SVN, under grok/doc/rules.txt:
> http://svn.zope.org/grok/trunk/doc/grok_rules.txt
> We need to think about how this would be integrated into the 
> documentation section of the website. I think it would make sense to 
> present this document on one page. Once it's a bit further along, I 
> think it would also make sense to make special reference of it on our 
> website. Kevin Teague, do you have any ideas on how we'd integrate it?

Short term: We could cut-n-paste the text into a "How-To" object on the
site. This would make all the text on one page. The document is long enough
that some might desire it to be broken up into smaller pages, in which case
it could be a "Tutorial" object - except this has the downside of syncing
future updates much more fiddly and time consuming.

Long term: I like Uli's start on using Sphinx as a tool for building
"official/reviewed" Grok documentation (and keeping the Plone Help Center
for community contributed content), so this document could be included as
part of that. This plan does create the work of finishing up the Sphinx doc
effort, updating the /documentation/ section of the site so that "official"
and "community" content is presented in a non-confusing manner, and ideally
making the official docs show up in the local site search. It is quite nice,
especially with Reference or Tutorial docs, to present the docs with a
minimum amount of extra elements on the page (e.g. navigation links to the
rest of the web site) - but then will people get confused as to why there
are two documentation sections and which one should they be looking in? I
guess it can be presented fairly clearly if we just have Tutorial,
Developer's Notes and Reference as Sphinx docs.

Unfortunately I have recently discovered that backcountry skiing is more fun
than maintaining web sites and updating documentation ( Lookit how sweet it
is! British Columbia is awesome!
http://flickr.com/photos/kteague/sets/72157604648314682/ ). Anyone willing
to contribute to the documentation or move forward web site efforts would be
bestowed with the most greatest of Karmas!

(ok, please poke lazy me if no one steps up for this before we release
one-point-oh ...)

View this message in context: http://www.nabble.com/Rules-of-Grok-document--how-to-integrate-this-into-the-website--tp16796947p16827993.html
Sent from the Grok mailing list archive at Nabble.com.

More information about the Grok-dev mailing list