Re: [Docutils-develop] Workflow for improving the Docutils Document Tree guide?

[Guenter M. <mi...@us...>]

Dear E. Dunham,

someone interested in helping to fill the gaps in our documentation is good
news.

On 2015-04-19, E. Dunham wrote:

> Some other docs linked me into a "to be completed" section of the DTD
> guide. The instructions for what to do with "to be completed" sections
> at http://docutils.sourceforge.net/docs/ref/doctree.html#to-be-completed
> don't provide any guidance on how the authors/maintainers would like
> changes to the guide to be submitted. 

> Could you please tell me what that workflow should be (probably check
> out a copy from some link or other, write changes according to certain
> standards, email a patch to some address?), so that I can add first the
> instructions and then hopefully a bunch of the missing sections to the
> guide? 

There is no established procedure for documentation separate from code
developement. I'll try to list some points:

* Get the latest version from the repository_ (either set up a working
  copy via SVN or git or download the file(s) in question via the web
  access).
  
* Mail your patches to the `mailing list`_
  doc...@li....
  
  This is also the place for questions arising during the process.

* For the style, see the Doctutils Policies, especially the
  `documentation conventions`_ and the rest of the document (and other
  Docutils documentation) to get a feeling for tone and style. Often, you
  can copy and edit parts from other places.
  
* Start with a small edit and wait for the feedback.

.. _repository: http://docutils.sourceforge.net/docs/dev/repository.html
.. _mailing list: 
   http://docutils.sourceforge.net/docs/user/mailing-lists.html
.. _documentation conventions:
   http://docutils.sourceforge.net/docs/dev/policies.html#documentation-conventions


I hope this can get you started...

Thanks, Günter