Contribute to the Documentation

Last update: Edit

1 Introduction

All Mendix 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 Studio Pro 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)

You can create and edit files online within GitHub. If you want to work outside GitHub, we recommend using the following tools to contribute to the Mendix documentation:

  • For writing, editing, and previewing documentation – Typora, Visual Studio Code, or Visual Studio Code in the browser (accessible by pressing . after opening your fork of the mendix / docs repository)
  • For committing your documentation – Sourcetree or GitHub Desktop

3 Editing the Documentation in GitHub

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 Leaving Feedback on the Documentation

If you find an issue with the documentation – whether that is a typo, a missing step, or a specific technical problem – we want to know about it so we can improve!

When you click the Feedback button on the right side of the screen, you will be brought to our GitHub repo’s Issues page. Please include the following details in your feedback:

  • The document you are working with
  • A detailed description of what is wrong
  • Details on what can be improved or what the fix is, if applicable
  • Screenshots of your Mendix Platform usage, if applicable

We look at all feedback and take it seriously, and we will be in contact about how to resolve it.

5 Writing New Documentation

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

5.1 Using a Template

To submit a new how-to or Studio Pro Guide page to the Mendix documentation, start with a Mendix documentation template:

5.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 App,” the filename should be create-your-app.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 extensions are allowed: .png (preferred), .jpg, .gif

5.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).

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

To access the license agreement, go to the the Checks section of the pull request’s Conversation tab and click Details for license/cla .

This only needs to be done once.

7 Read More