[Python-Dev] Moving the developer docs?

[Steven D'Aprano]

On Fri, 24 Sep 2010 01:50:34 am Steven Elliott Jr wrote:

> What I have done in various organizations has been to create a system
> where an official repository is kept with all of the *official*
> documentation and a way for users (developers) to submit their
> proposals as to what they would like to add and change.
[...]
> I do however, discourage the use of wikis at all costs. It has been
> said that they feel loose and unofficial, and although that my not be
> the intent, over time this becomes reality.

Surely that depends on how widely you give write-privileges to the wiki?

If you wouldn't give arbitrary people write-access to your documentation 
repository, why would you give them write-access to your wiki? If the 
wiki doesn't allow you control who has read and write access, then use 
a different wiki.

I'm not familiar with any wiki that doesn't allow you to track and 
review history of the documents. Some of them are just web interfaces 
to standard VCSes like Mercurial. Wikipedia is now experimenting 
with "pending changes" and having stable and unstable versions of 
pages.

I've known people to work themselves into a tizz at the thought of their 
developers making "unauthorized" changes to the documentation, while 
not even tracking changes to the source code *at all*, let alone 
reviewing the commits. This makes no sense to me at all -- if you 
(generic you, not you specifically) trust your developers to make 
changes to the source code, why not trust them to make changes to the 
documentation? The real problem, it seems to me, is the difficulty in 
getting developers to write and update documentation, not in preventing 
them from writing it.



-- 
Steven D'Aprano