[Doc-SIG] Improving the documenting process.

[Michael Foord]

David Priest wrote:
> On 2-Jan-06, at 8:03 PM, Chris Jerdonek wrote, in part:
> 
>>I wonder how wiki documentation compares to the best
>>individually-written Python documentation -- if the style gets
>>watered-down in the community process at all, and whether this
>>dissuades any writers.
> 
> 
> Using the wiki for documentation will only work well if there is a  
> structure for allowing a select group of editorial assistants to  
> control the "Real Documentation" (as opposed to the marginalia/ 
> discussion/questions/suggestions/etc part that would be somehow  
> closely related to the "Real" -- perhaps via a Talk page, a la  
> Wikipedia; perhaps via some Plone-like construct.)
> 
> In other words, we need a way that presents the official, well- 
> written, well-presented material *separate* from the public noise;  
> and we need editors who will actively take the good stuff from that  
> noise and use it in improving the official text.

I've been resisting replying to this thread, because I don't want to
just add more noise. However I think we *can* sort the workflow, and
that is a different question to what markup format is used.

I think that in order to improve documentation, encourage more
contribution, and get that contribution into the final docs we need :

1) An online system for contributing changes in *any markup* [#]_
2) Editors who take responsibility for specific areas of the documentation
3) Assistance for editors who need help turning user comments into LayTeX

I'm not just adding noise here - I'm happy to help by taking on
responsibility for *some documentation* and evaluating user additions.

This means that (1) *ought* to email the person responsible when a new
comment is made. It *ought* to include a system for marking comments as
accepted or rejected. Possibly allowing the administrator for a section
of documentation to delete rejected comments will be enough.

It also needs a login system (simple) to reduce spam.

For the sake of simplicity I would suggest that when a new version is
released old comments are *not* automatically migrated. Either they fall
by the wayside and can be re-submitted, or the documentation maintainer
can add them. An admin interface to allow migrating of comments from old
docs to new docs would be nice - but may or may not ever happen...

To facilitate (2) *someone* needs to break the documentation down into
areas and we need to sign up editors. They don't need to be the same
person who maintains the code. But they need to be approved by the BDFL
of the documentation (Fred L. Drake ?).

3) Can be done via this forum.

I hope this is helpful.

I'm sure we can use Ian Bickings commentary system as it stands - though
with the changes I've suggested above. (Some of which he's working on
anyway).

I'm happy to help, although I don't yet know LaTeX I do have writing
skills that I'd love to contribute.

This leaves markup as a separate question - but provides a good way of
getting user input to the docs. It's not really anything new, but let's
get it happening.

All the best,

Fuzzyman
http://www.voidspace.org.uk/python/index.shtml

.. [#] Actually we probably ought to restrict it to plain text, reST or
LayTeX.


> _______________________________________________
> Doc-SIG maillist  -  Doc-SIG at python.org
> http://mail.python.org/mailman/listinfo/doc-sig
> 
> 
>