Writing Documentation

Description

How to write and submit content for the Plone Documentation.

Reaching The Documentation Team

The Plone community runs a documentation team which is responsible for keeping the Plone documentation coherent. To reach this team for any questions please contact

For news and updates you can also follow PloneDocs on twitter.

Feedback

We need your feedback to make the documentation better !

If you have already a GitHub account, please do not hesitate to open a ticket in our issue tracker .

If you do not have one, please use the ‘Feedback’ widget on docs.plone.org .

Picture of feedback widget

Reporting Issues

Documentation Issues

Documentation issues are tracked in our issue tracker.

If you have already a GitHub account and you find something missing or wrong in the docs, please open a ticket.

One of the best ways to start contributing is to pick one of the tickets labeled First Timer.

Note

Working on issues takes time and energy, to make it as pleasant as possible for everyone, meaning for you and the reviewer we would like to ask you kindly to make yourself familiar with our style-guides for documentation and reStructuredText [reST].

Plone Issues

If you think your bug involves a core component of Plone, check to see if that component has its own repository under the Plone organization on GitHub.

If it does, use the component’s issue tracker to submit your bug report. If the component does not have its own repository there, submit your bug report in the catch-all CMFPlone tracker on GitHub.

Note: after figuring out where to post your report, but before doing so, please search the issue tracker to ensure this issue hasn’t already been reported and that it hasn’t already been fixed in a later version of the component.

You can also find a overview about that on plone.org.

License

The Plone Documentation by Plone Foundation is licensed under a Creative Commons Attribution 4.0 International License.

If you want to contribute to this documentation, you can do so directly by making a pull request, if you have filled out a Contributor Agreement.

If you haven’t filled in a Contributor Agreement, you can still contribute. Contact the Documentation team, for instance via our community space.

Basically, all we need is your written confirmation that you are agreeing your contribution can be under Creative Commons.

You can also add in a comment with your pull request “I, <full name>, agree to have this published under Creative Commons 4.0 International BY”.

Workflow

The documentation is hosted on GitHub. And there are tools hooked directly into it:

For these reasons, it is important we keep the documentation coherent. Therefore, we follow a simple workflow, which we ask all contributors to respect:

Please DO NOT commit to master directly. Even for the smallest and most trivial fix.

ALWAYS open a pull request and ask somebody else to merge your contribution. NEVER merge it yourself.

Your pull requests may be checked for spelling, and clarity. Don’t hesitate to contribute also if English is not your first language, we will try to be helpful in corrections without being annoying.

If you don’t get feedback on your pull request in a day please come to #plone-docs and ask.

The main goal of this process is not to annoy you. On the contrary, we love your contributions.

But the documentation team also wants to keep the documentation in good shape.

Documentation For Different Versions Of Plone

The documentation for the different versions (Plone 3, Plone 4, Plone 5) are organized in branches inside the Plone Documentation

The default branch points to the current version of Plone.

Documentation changes that are valid for multiple versions of Plone can be done by making multiple pull requests, or by cherry-picking which may be easier to do when branches are widely different.

When all this seems complicated, note in your pull request that you think this is valid for other versions of Plone as well, and the documentation team will take care.

Editing The Documentation On GitHub

This is the recommended way for smaller changes, and for people who are not familiar with Git.

  • Go to Plone Documentation on GitHub.
  • Press the Fork button. This will create your own personal copy of the documentation.
  • Edit files using GitHub’s text editor in your web browser
  • Fill in the Commit changes-textbox at the end of the page telling why you did the changes. Press the Commit changes-button next to it when done.
  • Then head to the green New pull request-button (e.g. by navigating to your fork’s root and clicking Pull requests on the right menu-bar, or directly via https://github.com/yourGitHubUserName/documentation/pulls), you won’t need to fill in any additional text. Press New pull request-button, finally click Send pull request.
  • Your changes are now queued for review under project’s Pull requests tab on GitHub.
  • For more information about writing documentation please read the styleguide and also this.
  • You will receive a message when your request has been integrated into the documentation. At that moment, feel free to delete the copy of the documentation you created under your account on GitHub. Next time you contribute, just fork again. That way you’ll always have a fresh copy of the documentation to work on.

Before You Make A Pull Request

  • Check for typos. Again, do not let this discourage you if English is not your first language, but simple typing errors can usually be found with spellcheckers
  • Make sure that all links you put in are valid.
  • Check that you are using valid restructured text.

Pull Request Checklist

Making a good pull request makes life easier for everybody:

  • The title and description of a pull request MUST be descriptive and need to reflect the changes. So please say “grammar fixes on the intro page” or “new page: feature x explained as a user story”

If you can state for which versions of Plone your submissions are valid, that would be awesome.

We use a template which creates a default form for pull requests

Picture of Pull request template

If possible please make sure to fill in the missing bits, for example

Fixes #1234

Improves:

-  Style-guide about reST syntax

Changes proposed in this pull request: Unified usage of '..code-block:: shell' as best practices

Editing The Documentation Using Git

This is the recommended method of editing the documentation for advanced users.

  • Learn about Sphinx and restructured text.
  • Fork the documentation source files into your own repository
  • Edit the file(s) which you want to update.
  • Check that you do not have any syntax errors or typos
  • Commit your changes and create and open pull request.

For more information about writing documentation please read the styleguide and also this.

Translation

We use Transifex for translation.

Quick Start:

Getting Started