Contributing To The Documentation

Note

Contributing to the docs is a excellent way to get involved, meet the community and to improve Plone !

Don’t hesitate to contribute also if English is not your first language !

Overview

The documentation is hosted on GitHub.

  • Different branches for the different versions of Plone.

  • Some external documentation is pulled in, to collect all the documentation in one place.

General Guidelines

Please follow these general guidelines.

  • 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.

  • If you work on a ticket, assign yourself to it.

  • Create ‘small’ pull requests, one per each file, these are easier and faster to review, think quality over quantity !

Edit In The Cloud

Head over to the documentation repository.

You can then click the Fork button in the upper-right area of the screen to create a copy of our site in your GitHub account called a fork.

Make any changes you want in your fork, and when you are ready to send those changes to us, go to the index page for your fork and click New Pull Request to let us know about it.

  1. Fill in the text-box Commit changes at the end of the page telling why you did the changes.

  2. Press the button Commit changes next to it when you are done.

  3. 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.

  4. Click Send pull request.

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

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 our docs about helper tools.

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, fork again. That way you’ll always have a fresh copy of the documentation to work on.

Before You Make A Pull Request

  • Before you commit your changes, it’s a good idea to run a spell check.

  • 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 should be descriptive and need to reflect the changes.

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 Docs Using Git

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

If you are already a member of the Plone organization on GitHub, create a branch in the documentation repository.

If you are not a member you can also create a fork of the documentation repository into your own repository.

  • Learn about Sphinx and reStructuredText.

  • 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 a pull request.

For more information about writing documentation please read the styleguide and the docs about Helper tools.