Contributing to the Documentation

Documentation is as important as code. It follows the exact same principles: DRY, tests, ease of maintenance, extensibility, optimization, and refactoring just to name a few. And of course, documentation has bugs, typos, hard to read tutorials, and more.

Tip

If this is your first time thinking about writing documentation, have a look at Writing great documentation from Jacob Kaplan-Moss, one of the authors of Django, an awesome Python web framework.

Contributing

Before contributing, you need to become familiar with the markup language used by the documentation.

The mangos-zero documentation is hosted on BitBucket:

https://bitbucket.org/mangoszero/documentation

If you want to submit a patch, fork the official repository on BitBucket and then clone your fork:

$ git clone git@bitbucket.org:YOURUSERNAME/documentation.git

The develop branch holds the documentation for the development branch of the code.

Create a dedicated branch for your changes (for organization):

$ git checkout -b improving_foo_and_bar

You can now make your changes directly to this branch and commit them. When you’re done, push this branch to your BitBucket fork and initiate a pull request.

Creating a Pull Request

Following the example, the pull request will default to be between your improving_foo_and_bar branch and the documentation develop branch.

Note

The mangos-zero documentation is licensed under a Creative Commons Non-Commercial Attribution-Share Alike 3.0 Unported License.

You can also prefix the title of your pull request in a few cases:

  • [WIP] (Work in Progress) is used when you are not yet finished with your pull request, but you would like it to be reviewed. The pull request won’t be merged until you say it is ready.
  • [WCM] (Waiting Code Merge) is used when you’re documenting a new feature or change that hasn’t been accepted yet into the core code. The pull request will not be merged until it is merged in the core code (or closed if the change is rejected).

Pull Request Format

Unless you’re fixing some minor typos, the pull request description must include the following checklist to ensure that contributions may be reviewed without needless feedback loops and that your contributions can be included into the documentation as quickly as possible:

| Q             | A
| ------------- | ---
| Doc fix?      | [yes|no]
| New docs?     | [yes|no] (PR # on mangoszero/server if applicable)
| Fixed tickets | [comma separated list of tickets fixed by the PR]

An example submission could now look as follows:

| Q             | A
| ------------- | ---
| Doc fix?      | yes
| New docs?     | yes (mangoszero/server#1250)
| Fixed tickets | #1075

Tip

Online documentation is rebuilt on every code-push to BitBucket.

Documenting new Features or Behavior Changes

If you’re documenting a brand new feature or a change that’s been made in mangos-zero, you should precede your description of the change with a .. versionadded:: 1.X tag and a short description:

.. versionadded:: 1.1
    The ``getCreaturesInRange`` method was introduced in **mangos-zero** 1.1.

Standards

All documentation in the mangos-zero Documentation should follow the documentation standards.

Reporting an Issue

The most easy contribution you can make is reporting issues: a typo, a grammar mistake, a bug in a code example, a missing explanation, and so on.

Steps:

  • Submit new issue in the BitBucket tracker;
  • (optional) Submit a patch.