[Grok-dev] Documentation process proposal

[Sebastian Ware]

11 mar 2008 kl. 15.23 skrev Uli Fouquet:

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

I believe that manual editing of the contributors list is a good thing.

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

Especially in this case.

>
>
> 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 ;-)

I agree 100%

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

I hope it is ok that I responded on the list :)

Mvh Sebastian