Best practices for documentation of complex projects

Dear community, by the time our projects become more and more complex. Of course we follow the Mendix Best Practices (correct naming, use of SUB etc.). What I’m currently trying to to find out is, how we can preserve the basic ideas behind the Microflows and the app in general in a way, that future developers will understand it? In doubt, the father/mother of the app is not reachable in a few years. The other way round, newbies in the team need to be able to find their way in the app without a longer training beforehand. So, what are your best practices to solve this gordic knot?  Thank you!
4 answers

In our team we always have two persons who are responsible for a module. Because indeed we also have those microflows that other do not dare to touch due to the complexity. In those microflows we always try to add documentation. That in combination with the other person who also knows the complex flow does help. And if you document which persons are responsible for which modules it will help when people transfer out of the project. Because it give you inmediately an overview where your gaps are and who to train.

And we try to gradually give a developer more responsibilities. So first give them the easy stuff and a long the way give them more complex cases and time with the persons responsible for the module to help the newcomers understand what is done in the module.





Thinking about this subject and acknowledging its importance is half the battle won. Taking Ronalds advice gets you even further. Adding to this I would like to stress the advantages of ‘Single responsibility’ of the SOLID-principles and of the Agile framework making us work in Scrum-teams.

Implementing ‘Single responsibility’ into your app will make sure you don’t make you flows overly complex. Each flow will only do one thing. It will make sure you will not have one flow first do some validations, then some calculations, then some object-changes. I have good experiences with projects where each entity also had one folder for it’s flows and rules. Thus creating a data layer between your database and the app’s functions. This takes a lot of activities out of your normal flow-logic.

Agile and Scrum help. For instance since it creates teams of programmers that all can get around in each part of the app, that peer-review each others work, both on solution-choices made and readability.

Last but not least: use a code quality tool. No need to adhere to them strictly, but they all do make sense and give good pointers. The first code-quality tool is Studio itself: for warnings in your own code 0 is the only correct number.


Hi Tjark,

Almost every item in Studio Pro has a documentation box. I try to write 1 or 2 sentences in the box when I think an attribute, access rule, association, or whatever can be unclear to a colleague or my future self. In microflows I usually place an annotation with date, name, user story, and sometimes a short description of what the purpose of the microflow is.

In complex microflows always add annotations to splits, iterators, etc, which might be complex. For me a rule of thumbs is, the longer I need beforehand to figure out the stuff to build, the more important the documentation and annotations are. In the future in case of rework, bug fixing, etc, your awareness of the complexity of the logic is probably a lot less. So you want to get a quick grasp and impact of the work that needs to be done. 

Don't mess around with separate documents, you need the info right where the work is done. Although if you right-click your project in the explorer pane in studio pro, you can export (part of) the documentation if you need it elsewhere.


Thanks for you answers Tim & Ronald. I will take your input with me and ask more questions later. :)