Mendix Community Writes the Docs
Mendix Community Writes the Docs by Adam Dupaski
Ask any technical writer and they’ll tell you that no matter how much you test and verify, you still can’t cover all possible scenarios in your documentation. What is more, technical writers often don’t know if their documentation is even useful, because it’s not easy to get feedback from end-users on what works and what doesn’t.
But there is a way to deal with this: bring the end-user into the documentation process by enabling them to write and edit content themselves. So as the Mendix Community grows and members look for more ways to be involved, we are opening up our documentation so that they can contribute to it. This is how Mendix works – we drive innovation by focusing on our experienced Community of users.
Community-Generated and Community-Maintained
All of the Mendix documentation is now hosted on GitHub. This means that it is open-source, and with a GitHub profile, you can work on the docs directly. Seen an inaccuracy that’s frustrating you? Or a typo (oh the horror!) that’s driving you crazy? Then all you have to do is click Edit on GitHub on the new Mendix documentation website (https://docs.mendix.com/) to enhance the docs with what you’ve learned while working with Mendix. You can even demonstrate your expertise by writing a new How-To guide on, for example, how to create business rules for the insurance industry or configure advanced security.
In the near future, we will be adding your documentation to your Community Profile so that your experience and authority can be shown to our customers and the Community as a whole. And even better, we are working on getting you Mendix points for your documentation contributions so that you can increase your Mendix level.
We believe this Community-generated documentation will cover the questions only Mendix Community members know need to be answered. The documentation will address the needs of the Community more fully, because the Community will play a key role in maintaining, improving, and expanding it.
There are many benefits to this. Instead of just planning, organizing, writing, copy editing, proofreading, and testing documentation in-house, we’ll have the whole Mendix Community involved. That’s over 30,000 members! In this way, we are gaining from the experience and insight of all the Community members. This will only make the quality, accuracy, and consistency of the Mendix documentation stronger.
Of course, the Mendix Technical Writers will continue to review all the incoming documentation so that it can be tested, proofread, and adapted to our style guide (for more information, see Content Writing and Formatting Guidelines). We have implemented a process for Developers, Testers, and Product Managers to review pull requests in order to maintain quality control. In addition, we have a documentation license and a contributors agreement mechanism in place.
If you want to contribute documentation but can’t quite find the words, we’re here to help. Feel free to contact us at firstname.lastname@example.org and we’ll work with you to generate some useful content!
New Documentation Means New Ways of Writing
This is a new way of doing documentation for everyone involved. Because we are hosting the documentation on GitHub, we are looking at the very essence of software documentation: the files. These files, written in Markdown, now occupy the same space as the code shared on GitHub. And with the GitHub workflow, developers can edit the Mendix documentation as easily as they edit code. Writing in Markdown means fewer formatting and styling options, but as is often the case with such limitations, the content will become clearer and more refined.
This migration to GitHub also means moving away from the idea of proprietary documentation and knowledge management. We are emphasizing the role of contributor rather than just sole author, because the ownership of the documentation will be Community-defined.
We’re excited about the Community contributing to the Mendix documentation, because it meets two major goals: a higher quality of documentation and more Mendix Community involvement. You can check out How to Contribute to the Documentation for more details on how this all works.
We look forward to your writing!