[Grok-dev] Documentation process proposal

[Uli Fouquet]

Hi Sebastian,

Sebastian Ware wrote:

> I have a question regarding stating the author
> 
>    :Author: ME GROK

You spotted one of the really new proposals! Good eyes :-)

> is this the way it is supposed to be done in Plone? In the content  
> meta data you can set "Creators". Currently though, "Creators" don't  
> seem to be rendered on the public views.

Right. The marker mentioned above is restructured text specific and (at
least currently) has nothing to do with Plone. We got that
`contributors` meta data in Plone, but it seems not to be updated
automatically under all circumstances. You have to do it manually and
most people forget. Sometimes this is okay, because fixing some typos
can hardly be called a substantial contribution.

More problems arise if someone called 'admin' grabbed a doc from the
filesystem or elsewhere and put it on the website: who's the one to get
fame or shame for the document? Plone will erraneous tell, that 'admin'
is the author and this even only, if you are logged in. 

The main reason behind the 'tell-your-name' thing is, that I think
authors should take responsibility for their docs (as code writers do
for their code) and also earn credits for their work. This might ease
the work of any documentation maintainer, because he/she knows whom to
ask in case of trouble, say, a new grok release. Do the examples shown
in a doc still work? Most of us simply can't be informed about all
topics in-depth, which are available on the website (well, maybe the
Dutch can ;-)

That's exactly one of the topics I'd like to discuss (here or in the
wiki). So thank you very much for that question!

Best regards,

-- 
Uli

-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 191 bytes
Desc: Dies ist ein digital signierter Nachrichtenteil
Url : http://mail.zope.org/pipermail/grok-dev/attachments/20080311/4fb7811e/attachment.bin