Contribute to Mendix Docs

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 teaches 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 at Join GitHub)

You can create and edit files online within GitHub. If you want to work outside GitHub, Mendix recommends 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 and Pull Request Workflow.

4 Leaving Feedback on the Documentation

If you find an issue with the documentation—whether it 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:

• To get the how-to template, right-click this link and save the file locally: How-to Template
• To get the reference page template, right-click this link and save the file locally: Mendix Studio Pro Guide Page Template

5.2 Guidelines and Conventions

Follow these guidelines and conventions when writing:

• Reference and use our Documentation Writing Guidelines
• Make sure the Markdown file name reflects the title of the page (for example, if the page is titled “Create Your App,” the file name should be create-your-app.md)
• Name the Markdown and image files in lower-case with a hyphen (-) between each word, and do not use spaces or any other symbols in the file name (for example, &), as these will not be accepted
• When creating screenshots:
  • Make sure the resolution of your screen is 100% (or a multiple thereof) so that your images are sharp
  • Focus on the part of screen that contains the information you need so that the browser does not have to shrink the image when it displays it, and crop the image closely
  • Make sure the image file has a name that makes sense so it is easy to find it
  • Save the image as a .png (preferred), .jpg, or .gif file
  • Save the image file in a sub-folder in the attachments folder for the location of the document (this sub-folder should have the same name as the document file name you are working on)

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

• Documentation Writing Guidelines