Vision¶
About motivations and goals of the documentation-style-guide-sphinx project.
Context¶
In software development, documentation matters.
Sphinx [1] is a great documentation builder. It is community standard for Python [2] projects, but is not tied to Python and can be used to document almost everything. One of his strength is to use the reStructuredText [3] syntax, which focuses on simplicity and readability for humans.
As of may 2012, Sphinx’s reStructuredText primer [4] and docutils’ reStructuredText documentation [3] focus on syntax. They give examples, but they are quite permissive.
When developers contribute to projects, they read and write documentation. There are conventions about writing code, but there is no about writing documentation. So documentations, despite they are based on a common toolkit, are really heterogeneous:
- the more developers, the more heterogeneous.
- every project may use its own conventions.
Goal¶
Feature: public sphinx style guide
In order to improve readability of documentation and make it consistent
across the wide spectrum of Sphinx-based documentations
As member of a development team
I want to follow style conventions.
Scenario: Adopt documentation-related conventions for a project
Given a project
And a team
When the team chose Sphinx as documentation builder for project
And the team needs conventions about the documentation
Then team members follow the rules provided at
http://documentation-style-guide-sphinx.readthedocs.org/
And reference it in their project's documentation.