Top 2 Approaches to Generate Project Documentation in the OutSystems Platform
Concepts for Big Projects #4
This series is a compilation of challenges, approaches, and solutions that were part of our path as OutSystems Developers throughout different projects.
Keep in mind that many resources, tips, tricks, and techniques were also shared with us in various articles and forums by peers and colleagues. We decided to share what we have been learning in our journeys in the hope that it can also bring value to you.
As we face different challenges, this series will include various random topics. Stay tuned.
Managing OutSystems Documentation
As a best practice, it goes without saying that every project should be documented. However, on big projects, documentation is essential to manage the complexity, define standards and guidelines, and make informed decisions.
Additionally, the bigger the project more questions arise on how to handle the whole scope of relevant information and how to automate as much as possible its production:
How should we generate Design documentation for an Application or a Solution?
How many screens need to be retested after refactoring?
Can you get a list of all the APIs of a domain?
Can I generate a catalog of public elements for the developers to search?
The good news is that the OutSystems platform lives on top of a metamodel where you can extract useful information. The OutDoc forge component (supported by OutSystems) can extract information related to the modules and automatically generate documentation. But you may need to develop additional tools or features to manipulate and exhibit this information structured in the way required.
To help you understand the platform's boundaries in generating design documentation or reports for your specific needs, we explore two approaches: using the platform Metamodel information, and the OutSystems OutDoc Forge Component.
#1 Approach – OutSystems Platform Metamodel
By consulting the system's entities, you can manually find all the information related to the platform's management, like applications, modules, entities, site properties, timers, etc. With this information, you can, for example, list all the modules and related applications.
For additional exploration on the Platform Meta Model, Check the following article:
However, instead of extracting the needed information yourself, we suggest using the forge component OutDoc.
#2 Approach – OutSystems OutDoc Forge Component
This tool automatically generates documentation by extracting the modules' design documentation.
Internally, OutDoc gets the most recent version of the module's binary and converts it to an XML.
Image 1 – OutSystems Service Studio - Module OML conversion to XML
The generated XML will look like this:
Image 2 – Example of XML file generated of an OML
To help understand the tags used inside the generated XML, you can find more information inside the OutDoc tool itself on the Doc API tab:
Image 3 – OutDoc – Doc APIs (XML Tags)
Image 4 – OutDoc - Doc API details (Example)
To explore examples of extending OutDoc capabilities and customizing your documentation, you can look into:
Tips and tricks
When you have a big factory with thousands of modules, sometimes, we face issues generating the module's documentation.
Image 5 – OutDoc - Error while generating documentation
This issue is sometimes related to a module that needs to be recovered. We needed to apply a recovery instruction on the command line to work around this issue. To do that, we followed the steps below:
Download the Module – The module that was raising the error while generating the documentation ought to be downloaded (From Service Studio or Service Center);
Open the Command Line as an Administrator;
Use the following command to open Service Studio with the module in Recovery Mode;
"<path_to_service_studio>\ServiceStudio.exe" -recover <path_to_oml_file>\<oml_file_name>.omlPublish the module.
This action will recover the metadata needed to generate the XML of the OML file.
Conclusion
There are several forge tools that you can use to generate your documentation (OutDoc, Timer Map, OutDoc Release Report, OutDoc Reusable Components, etc.).
Further, you can extend the existing tools to tailor the generated documentation to your project's requirements and thus get the reports you need.
Finally, we couldn't end this article without mentioning the basic rule of thumb: to get excellent and helpful documentation, it is of the utmost importance to thoroughly describe all elements throughout the application development. It might sound like an exaggeration, but this effort will ultimately pay off.
Resources
Previous articles:
This article is a part of a series on Concepts for BIG OutSystems Projects. Take a look at the others if you would like to learn more:
Like this article? Share it:
