User discussion for the docutils project.

Benoît Bryon | 13 May 2012 17:22

Style guide for documentation

Hi,

I am posting this message on docutils-users, sphinx-dev and doc-sig
mailing lists:

*  <at> docutils-users, it's a proposal about some "restrictive"
  reStructuredText subset;
*  <at> sphinx-dev, it's about Sphinx usage, i.e. best practices;
*  <at> doc-sig, I wonder if it could be a PEP for documentation of Python
  packages.

I started to write down conventions for Sphinx-based documentations at
https://github.com/benoitbryon/documentation-style-guide-sphinx

I'd like to share this work, and I also need feedback.
I guess it could be compared to PEP-8, as a "style guide", but applied
to Sphinx-based documentations.
Python code can be valid even if it doesn't follow PEP-8; but Python
code should follow PEP-8 because it's the convention (and de facto 
best
practice).

More explanations below.

Story
=====

As a developer, I started using Sphinx five years ago. I contributed 
to
documentation of public or private projects using Sphinx. I also

(Continue reading)

headers

sam kleinman | 18 May 2012 04:07

Re: Style guide for documentation

I think most people just follow the conventions of the python
documentation project. 

I actually don't think that this matters particularly much. 

Different projects have different needs, rst doesn't "care" too much
which order you use underlines for headings as long as you do
conceptually "wrong" things, which is what you care about from a
documentation writing prospective. 

My day job is as a technical writer doing stuff with sphinx and
restructured text (without Sphinx,) and the biggest barrier isn't the
style of the text files, but the conceptual background to actually be
able to write content that's relevant and appropriate, to say nothing of
actual writing skills. 

A style guide would be one thing to spend a lot of time writing, that I
don't think would have any real impact on the quality of
documentation. 

Conversely, I think people might be able to create some style and
perhaps even enforce it, but I don't think that would actually force
people to write more clear sentences, to be able to structure text
inductively, to use indexing more effectively, to effectively structure
sections and documents in a hierarchy.

So unlike python where PEP 8 actually makes python code more
maintainable, and less prone to errors. Maybe it *would* be a good idea
to increase the number of warnings, or include some sort of ``rstlint``
package that provided some sort of basic analysis of your RST source

(Continue reading)

headers

Benoît Bryon | 21 May 2012 16:50

Re: Style guide for documentation

Le 18/05/2012 04:07, sam kleinman a écrit :
> I think most people just follow the conventions of the python
> documentation project.
Do you mean: conventions of the docutils project?

As an example, let's consider sections:

* basics and examples from docutils documentation:
   http://docutils.sourceforge.net/docs/user/rst/quickstart.html#sections

* convention from Sphinx's documentation:
   http://sphinx.pocoo.org/rest.html#sections

* a sample from Python library documentation:
   http://docs.python.org/_sources/library/stdtypes.txt

* another sample from Python library documentation:
   http://docs.python.org/_sources/library/string.txt

Where is the convention?
In fact there is at least one in Sphinx documentation, but who
follows it? Even the code sample in the Sphinx documentation
doesn't use it.

> I actually don't think that this matters particularly much.
>
> Different projects have different needs, rst doesn't "care" too much
> which order you use underlines for headings as long as you do
> conceptually "wrong" things, which is what you care about from a
> documentation writing prospective.

(Continue reading)