Contribute to the Documentation

Last update: Download PDF Edit

1 Introduction

The documentation is open to the Mendix community, which means you can make changes and add to it in ways that you see necessary. Do you see a how-to that is inaccurate or a section of the reference guide that needs to be updated? You can easily help us improve the documentation for the whole Mendix community!

All the Mendix documentation is stored in a GitHub repository. With a GitHub account, you can edit all existing documentation. You can also write a new how-to on an awesome topic of your choice and submit it.

To work on the documentation in GitHub, use Markdown. For details on this easy-to-use syntax, see the GitHub Guide to Mastering Markdown.

This how-to will teach you how to do the following:

  • Add to and edit existing documentation
  • Create new documentation

2 Prerequisites

Before starting with this how-to, make sure you have completed the following prerequisites:

  • Have a GitHub account (sign up here)

We recommend using the following tools to contribute to the Mendix documentation:

3 Editing the Documentation

To edit existing documentation, follow these steps:

  1. Click Edit in the upper-right corner of the specific Mendix documentation page that you want to work on.
  2. Make your changes in GitHub (make sure the changes align with our Documentation Writing Guidelines).
  3. Create a pull request that specifies our development branch as the base. For more information, see Creating a Pull Request and GitHub Standard Fork & Pull Request Workflow.

4 Writing New Documentation

The sections below present the key steps in writing new documentation for Mendix.

4.1 Using a Template

To submit a new how-to or reference guide page to the Mendix documentation, start with a Mendix documentation template:

4.2 Guidelines & Conventions

Follow these guidelines and conventions when writing:

  • Reference and use our Documentation Writing Guidelines
  • Make sure the document files comply with these naming conventions:
    • Markdown file names should have the same name as the title of the page (for example, if the page is titled “Create Your Project,” the filename should be create-your-project.md)
    • Document file names should always be lower-case with a hyphen (-) between each word
    • Do not use spaces or any other symbols in the file name (for example, &), as these will not be accepted
  • Make sure the image files comply with these naming conventions:
    • Image file names should always be lower-case with a hyphen (-) between each word
    • Do not use spaces or any other symbols in the file name (for example, &), as these will not be accepted
    • Make sure the image files have names that make sense so it is easy to find them
    • Save the image files in a sub-folder in the attachments folder for the category in which the document is located (this sub-folder should have the same name as the document file name you are working on)
    • The following image file types are allowed: .png (preferred), .jpg, .gif

4.3 Submitting Your Work

When you are ready to submit your work, follow these guidelines:

  • Commit new Markdown files via Sourcetree or via the Create new file button in the Mendix GitHub repo (where you can copy-paste your text)
  • Commit new image files via Sourcetree or via the Upload files button in the GitHub repo (where you can drag and drop your image files)

Finally, create a pull request that specifies the Mendix development branch as the base (for more information, see Creating a Pull Request).

5 Signing the Contributor License Agreement

The first time you make a contribution to the Mendix documentation (via a pull request), you need to sign the Contributor License Agreement for mendix/docs via CLAHub.

To access the license agreement, go to the Conversation tab of the pull request and click Details for clahub:

This only needs to be done once.

6 Gaining Mendix Points

As you add knowledge to the documentation that will help your fellow Mendix developers, you will gain Mendix points for each contribution!

Before you can receive Mendix points for your documentation contributions, you must authorize the connection of your GitHub profile to your Mendix Community Profile. For more information, see the Authorizing GitHub Connection section in Mendix Profile

The amount of points you gain depends on the size of the documentation contribution you make. This is calculated per pull request and is based on the number of lines changed:

  • For a small contribution to the documentation – 5 points
  • For a large contribution to the documentation – 15 points

The points are awarded when the pull request is merged.