We need clear and concise guidelines for documentation writers

[timlinux]

Problem

As more people participate in our documentation project there is scope for wildly different documentation styles and a general degradation of the quality of our documentation.

Currently we have http://inasafe.linfiniti.com/en/developer-docs/maintaining_documentation.html which provides some basic info on how to write documentation but it is not adequate to fully orientate new documentors into our system.

Proposed solution

• split http://inasafe.linfiniti.com/en/developer-docs/maintaining_documentation.html into two - one document for API documentation style guide, one section for user documentation style guide.
• Ensure the API documentation guide is self contained with outward links to rst and user documentation where relevant.
• For end user documentation, detail the key markup elements that should be used and other important aspects that should be taken care of when writing sphinx documentation.
• Add a new section on the procedures needed to setup a host (initially targetted to linux only) so that it is possible to compile the documentation locally.

See also

Issue #3

Expected Outcome

Providing clear guidelines and regularly auditing the documentation to ensure guideline compliance will prevent the documentation from losing quality over time

[mach0]

Done with SHA: 95ed9d6