[Grok-dev] New Grok site: restructured text and HTML

[Uli Fouquet]

Hi there,

Kevin Teague wrote:

> Descriptions must be plain, unformatted text as wiggy pointed out.
> They get used in RSS feeds and other contexts where ReST and HTML  
> don't make sense. I filed a bug in PHC about this, and am planning on  
> submitting a fix for this as well.

Cool. Thanks for that, although it's really not a showstopper.

> Kupu is better than anything :). I wrote some docs in ReST, but then I  
> reverted to HTML because it's what I'm comfortable with. I'm getting  
> more comfortable with ReST though - I wrote the "our preferred format  
> is ReST" doc in ReST :).  It would be very cool if Kupu generated  
> ReST ...

Welcome to Editor Wars 2.0 ;-) But yes, that would be really cool.


> > There is also the possibility to stop maintenance of `doc/` in the  
> > grok
> > trunk or to reduce it to a minimum number of README files pointing to
> > the website. Then it wouldn't matter, in which format documents are
> > created. The drawback would be, that there would be no 'canonical'
> > documentation of certain versions. Switching to HTML also in the trunk
> > documentation is not an option IMHO.
> >
> 
> We should definitley clean-up the doc/ directory in Grok. There are  
> things like the old static web site publishing tool, which we ship in  
> the Grok tarball which it makes no sense to do.

There's a new tool to come, which is nearly finished.  IMHO it makes
sense to have the core documents (reference, the tutorial/book and maybe
a set of HowTos) as part of the local Grok documentation, so that you
can use it offline and watch the documentation for a certain release.

A tutorial/book for version 0.10 for example, has to explain permissions
different than a 0.11 version tutorial. That's why I think having docs
with the trunk is fine.

On the other hand we should really get rid of old stuff and only include
essential docs. We should really not keep thousands of docs from the
grok-PHC in the trunk ;-)


> The Tutorial and the Reference API are the big ones to have in the / 
> doc/ directory right now.

Agreed.

>  Figuring out which docs to pull from the web  
> site and how is a bit of a project. There are currently 1600+ pages in  
> the plone.org documentation area, it makes sense that we will over  
> time address the "long tail" of Grok documentation on the web site and  
> have docs that are of only marginal interest to many Grokkers. We  
> could perhaps have a keyword, or just pull the highlighted content out  
> the site for inclusion into /doc/.

What's the most plonish way to mark content for this purpose?

Kind regards,

-- 
Uli