A guide to write Documentation for Plone and for Plone Add-ons
Having a 'best practices' approach for writing your documentation will benefit the users 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.
Guides should be informational, but friendly. Use the active voice whenever possible, and contractions and pronouns are acceptable (in particular, the use of you in regards to the reader).
Use common sense – if a term is related to a high-level concept that fewer people would know, then take a sentence or two to explain it.
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.
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:
- 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)
- 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.
- The '/docs' directory should contain only content related to documentation, please do not put the license here. A LICENSE.rst with a short description of the license, and LICENSE.GPL for the legalese should go into the top level of your package next to your README.rst
- 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.
- Please follow our Word choice.
- 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.
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.
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: email@example.com License ------- The project is licensed under the GPLv2.
Feature-level changes to code are tracked inside
The title of the
CHANGES.rst file should be
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.
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 extension of .rst, but you don't specify that extension in the toctree directive)