From benoit at marmelune.net  Mon May 14 09:46:08 2012
From: benoit at marmelune.net (=?UTF-8?B?QmVub8OudCBCcnlvbg==?=)
Date: Mon, 14 May 2012 09:46:08 +0200
Subject: [Doc-SIG] Style guide for documentation
Message-ID: <4FB0B840.7010009@marmelune.net>

Hi,

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

* @docutils-users, it's a proposal about some "restrictive"
  reStructuredText subset;
* @sphinx-dev, it's about Sphinx usage, i.e. best practices;
* @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 some years ago. I contributed to
documentation of public or private projects using Sphinx. I also worked
in several teams with different background:

* private projects with Python developers working in the same company:

  * Python projects
  * PHP projects (yes, Sphinx is great to document a project, even if
    is not a Python project)

* public projects, with people I didn't know before.


I feel we lack some restrictive convention:

* in each team, RST usage differ. As an example, one team choose .rst
  extension (sphinx-quickstart's default), whereas another choose .txt
  (docutils recommendation).
* often, RST usage differ within documents of a project, depending on
  the original author: one developer uses "=" for first level of sections
  whereas another uses "-" symbol.
* and many more use cases...
* as a new contributor, when I joined a project or team, I spent too much
  time discovering conventions of the project. About documentation, I
  had to read current project's documentation, and often there was no
  convention at all.
* when I tried to propose conventions in a team, we had discussions.
  Again it's time we'd better spend on development than on discussion.
  I mean it's important to discuss and to share vision, but for this
  particular topic we should have used an existing convention, we
  shouldn't have asked.
* when I proposed the convention from one team to another, we discussed
  it again. With other argues, and potentially a different convention at
  the end :'(

That's why I started to write down conventions in a collaborative place,
so that every team can use it, reference it and contribute to it:

https://github.com/benoitbryon/documentation-style-guide-sphinx


Key features
============

* more restrictive than reStructuredText: as told by the Zen of Python,
  "There should be one-- and preferably only one --obvious way to do it."
* focus on use case: Sphinx-based documentation for a project.
  As an example, use Sphinx's specific directives.
* provide more than just syntax. As an example, recommend usage of
  target-notes directive at the end of a document, instead of using
  inline hyperlinks.


Feedback required
=================

* I wonder whether such conventions already exist or not.
* I wonder whether I should maintain a standalone convention or contribute
  to Docutils, Sphinx or even Python via a PEP... In fact, I guess I'd
  rather contribute, but I am not sure...

  * maybe reStructuredText documentation could include some of the
    proposed conventions as recommendations, so that users naturally
    use these conventions.
  * maybe Sphinx documentation could recommend some points in its
    reStructuredText primer.
  * maybe a PEP could recommend every Python developer to follow some
    style guide when they write Sphinx documents.
  * ... other suggestions are welcome!

* if you are interested in the project, use it or open issues!


Regards,

--
Benoit Bryon