Documentation Styleguide for Add ons

Description

A guide to write Documentation for Plone Add-ons

Introduction

Having a 'best practices' approach for writing your documentation will benefit the users of your add-on, and the community at large.

Even better: when there is a clear structure and style for your documentation, the chances that other people will help improve the documentation increase!

Further advantages of following this guide:

  • The documentation can be included on docs.plone.org
  • It will be in optimal format to be translated with tools like Transifex.
  • Unicorns will come and play in your garden. No, really.

Documentation structure & styleguide

For including documentation into docs.plone.org, please follow these guidelines:

  • All documentation should be written in valid ReStructuredText There are some Helper tools for writing Documentation available.
  • The top level of your package should contain the following documentation-related files:
    • README.rst This should be a short description of your add-on, not the entire documentation! See the README example
    • CHANGES.rst This should track the feature changes in your add-on, see Tracking changes
    • CONTRIBUTORS.rst This should list the people writing, translating and otherwise contributing
  • All of your (longer) end-user documentation should go into the /docs subdirectory. Feel free to split your documentation into separate files, or even further subdirectories if it helps clarity.
  • Make absolutely sure there is a start page called index.rst. It is also usually a really good idea to have that include a Table of Content, see Table of Contents for your documentation
  • use relative links for internal links within your /docs/ directory, to include images for instance.
  • If you want to include images and screenshots, you should place them into /docs/resources/ , along with other resources like PDF's, audio, video, etcetera. (Yes! Make more screenshots, we love you! But do remember, .png or .jpg as file formats, no .gif please)
  • Include a /docs/LICENSE.rst with a short description of the license, and /docs/LICENSE.GPL for the legalese.
  • Please do not symlink to, or use the include directive on files that live outside your '/docs' directory.
  • Please do not use 'autodoc' to include comments of your code.
  • Please follow this ReST styleguide and use semantic linefeeds. Do not break your sentences into half with newlines because you somehow think you should follow PEP8. PEP8 is for Python files, not for ReStructuredText.
  • Usage of Sphinx within your project is optional, but if you want your add-on to (also) be documented for instance on Read The Docs it is highly recommended. Put the associated Makefile and conf.py into the /docs directory.

Your documentation is not code.

Let's repeat that, shall we?

Your documentation is not code.

It needs to be translatable. No, not into PHP, but into Chinese, Catalan, Klingon, ...

Think about it this way: each sentence in the documentation can be turned into a .po string. Breaking sentences with linebreaks would mean a translator will only see part of the sentence, making it impossible to translate.

Note

If you use bobtemplates.plone to generate the layout of your add-on, the recommended files will already be there, and in the right place. You'll still have to write the content, though.

README example

This is an example of how a README.rst should look like: 

collective.fancystuff
=====================

collective.fancystuff will make your Plone site more fancy.
It can do cool things, and will make the task of keeping your site fancy a lot easier.

The main audience for this are people who run a chocolate factory.
But it also is useful for organisations planning on world domination.


Features
--------

- Be awesome
- Make things fancier
- Works out of the box, but can also be customized.
  After installation, you will find a new item in your site control panel where to set various options.


Examples
--------

This add-on can be seen in action at the following sites:
- http://fancysite.com
- http://fluffystuff.org


Documentation
-------------

Full documentation for end users can be found in the "docs" folder.
It is also available online at http://docs.plone.org/foo/bar


Translations
------------

This product has been translated into

- Klingon (thanks, K'Plai)


Installation
------------

Install collective.fancystuff by adding it to your buildout:

   [buildout]

    ...

    eggs =
        collective.fancystuff


and then running "bin/buildout"



Contribute
----------

- Issue Tracker: github.com/collective/collective.fancystuff/issues
- Source Code: github.com/collective/collective.fancystuff
- Documentation: docs.plone.org/foo/bar

Support
-------

If you are having issues, please let us know.
We have a mailing list located at: project@example.com

License
-------

The project is licensed under the GPLv2.

Tracking changes

Feature-level changes to code are tracked inside CHANGES.rst. The title of the CHANGES.rst file should be Changelog. Example: 

Changelog
=========

1.0.0-dev (Unreleased)
----------------------

- Added feature Z.
  [github_userid1]

- Removed Y.
  [github_userid2]


1.0.0-alpha.1 (yyyy-mm-dd)
--------------------------

- Fixed Bug X.
  [github_userid1]

Add an entry every time you add/remove a feature, fix a bug, etc. on top of the current development changes block.

Table of Contents for your documentation

Make sure all .rst files are referenced with a Table of Contents directive, like this example: 

.. toctree::
   :maxdepth: 2

   quickstart
   working_examples
   absolutely_all_options_explained
   how_to_contribute

(note: the files themselves will have an extention of .rst, but you don't specify that extension in the toctree directive)