A practical approach to OutSystems project documentation
In the OutSystems Developers community, many of you are, or were, somehow involved in “moving train” projects where applications were designed by some and developed by others. By the time you start(ed), most of these people aren’t in the project anymore. This shouldn’t be an issue!
In my opinion, the more exposed we are to different realities, the more we learn, but I’ll leave this topic to another article. The problem starts when we leave the project without leaving the minimum amount of documented information we would have wished to receive from others on our 1st days.
There are many reasons for that, and I am sure that by now, a couple of them have already popped into your mind. However, in the end, if there is anyone to blame is yourself because you accepted those conditions. Again, another topic for another moment :)
So, what should be the minimum amount of documentation we should create to guarantee others don’t go through the same moments of pain we went to understand the outcomes of those projects? Or, as many might say, what the hell happened there?! ;)
The bigger the OutSystems factory is, the more important it is to document what was done. Another relevant factor, for me, is the purpose of the factory since that will drive the way documentation can be created:
The main purpose of my factory is to create applications/products connected around the same Line of Business. In this use case, documentation should reflect the different domains composing the applications/products.
In my factory, I will support the growth of several applications throughout the vast number of Line of Business in my organization. This use case promotes the creation of documentation that follow the segregation of the different Line of Businesses.
Those that have read my past articles (Alert: the internet has much more interesting content) might notice similarities with how I structure Teams in Lifetime. It follows the same pattern, not because there is a need to authorize or limit access to the documentation but more from the perspective of who owns the documentation. The Team that owns the code also gives coherence to the overall processes.
There are different roles in a Team: Product Owner/Engagement Manager, Tech Leads, Developers, Testers, etc., but all should be responsible for producing and maintaining documentation at their level. The questions now are what to document, when to document, and where should we write our documentation?
Let’s start from the latter…
WHERE
Tools like Jira and Azure Dev Ops are typically used to support the Delivery Process, and all have features to host and maintain all the needed documentation. Nevertheless, there are still situations where those platforms are not within reach, and in this case, our old friends Microsoft Office and/or Google Docs can help us. There aren’t many excuses here; people just need to use them!
WHAT
User stories are one of the key aspects of documentation. The time invested not only ensures the correct guidance of the team members but also produces an extensive (business) knowledge base that is available for consultation once they are closed. However, the time invested in them doesn’t make them the only documentation needed. In my opinion, there are at least three more documents, from a technical perspective, that are very important to create:
Release Book
Architecture Overview
Integrations Overview
The Release Book is where you document all the needed information to support your deployment process: Site Property values, Timers 1st executions/configurations, Web Services endpoints, Mobile App builds, Security policies & actions (CSPs, certificates, …), and other configurations…
Architecture Overview is where is documented the application design. This is a live document and grows as the applications grow. I usually start with one document per business application and eventually create a master one to describe/design the macro/factory concepts that link the business application documents together.
The Integrations Overview document, as its name suggests, is where the integrations with the external systems and the created OutSystems APIs are documented. It follows the same approach as the Architecture Overview, where it becomes an integration base document that evolves into a group of documents once the number of different integrations starts to be part of the delivery.
WHEN
As soon as possible and therefore the title of this article: Don’t leave for tomorrow what you can do today! The sooner you have your work documented, the better. It works the same way as exercise. First, you feel it as an obligation, but with time it becomes a part of you. I just hope you don’t quit! :)
In the last couple of years, I have been involved in more projects/factories that have existed for 5+years than actually having the possibility to start a project from scratch, and the pains of going through the endless number of modules without a minimum amount of documentation made me more conscient about this issue.
Teams are pressured to continuously deliver functionality over functionality, and the proper awareness of a structured delivery process is diluted over time. However, in those moments when they need to onboard new colleagues or request external help, they don’t have enough documented knowledge to support those actions making them more costly than they need to be.
This article was written based on my experience throughout the years working on different projects from different lines of business with different levels of governance maturity and different Team sizes. Other use cases might need different approaches, and different people/processes might mean different ways of working. However, I found it very helpful to have a baseline to start the conversation and the thinking process. This is just one more baseline — mine!
Comments