As the title may suggest, there is a widespread misconception when it comes to Documentation in an Agile setting. This misconception is amplified when a technology platform is involved that enables organizations to rapidly adapt to the changing dynamic. Low Code Platforms such as the Microsoft Power Platform are typical examples that enable rapid adaptation.
During one of the more challenging projects, I overheard an interesting discussion between the Lead Infrastructure Architect and the Project Manager for Application Development.
At some point during their conversation the Infrastructure Lead asked to the Project manager: “Where can I find the documentation of the Power Platform Solutions your team has developed throughout the years?”. The Project Manager’s response: “We don’t have any. We work Agile”. You can imagine, I was flabbergasted by that response.
In a previous Blog Post, I already mentioned that I would spend an article covering the topic of Documentation, and more specifically Agile Documentation in a Low Code context. Statements like those of the Project Manager are indicative of this deeply held belief that Agile does not require documentation. In this month’s article I will explain why this belief is simply wrong.
What is Agile Documentation?
By now, you probably noticed that I prefer PMI’s Agile framework. What does PMI say about Agile Documentation? Well, let’s see:
- Invest in quality over documentation.
- Write documentation that is just barely good enough.
- Document stable concepts, not speculative ideas.
- Find better ways to communicate.
- Recognize that you need some documentation.
- Work closely with stakeholders
Let’s map these strategies to a Low Code context:
- Invest in quality over documentation.
It is a fact that better designed Low Code Solutions require less documentation. By ensuring that your Low Code Solutions are intuitive and easy to understand, you spare yourself the effort to create (non-maintained) documentation afterwards. Make use of the Power Platform Creator Kit to present the users with modern User Interface elements consistently across Power Platform Solutions. If the organization does not (yet) have a Design System, because the organization is too small or immature, tap into Google Material Design and Microsoft Design for inspiration. Also, Kristine Kolodziejski is a well-known Power Platform UI specialist. Be sure to check out her videos. Take note of the many available Power Platform Design Patterns. The one question you should ask yourself when you are creating or adapting your next Power Platform Solution: will it be easily understandable to a 10-year-old? This is a key design principle that Apple products are known for. Let me ask the following question: Why does the typical in-house developed Low Code Solution often seem more complex than the Commercial-Of-The-Shelf alternative….? Food for thought!
- Write documentation that is just barely good enough.
In other words: do not document more than is necessary. If the complexity level of the domain the Low Code Solution addresses is relatively low, do not try to be the whizz kid by coming up with a 100-page document. Even I tend to make that mistake sometimes. In fact, there are several factors that you need to take into account to decide the degree of detail. Invest more time in documentation in the following circumstances:
Medium to High Complexity -and Risks, Mandatory Compliance Guidelines. Think of a scenario where you have a Power Platform Solution integrated with several systems: internal -and external databases, webservices, integrations with highly secured governmental agencies, etcetera. Often these types of Solutions are critical to the organization’s core operations. Also, these integrations usually require the logic to be managed through dedicated orchestration -and integration layers, such as Azure Integration Services. In these situations, it is obvious that some time will need to be spent to produce the necessary documentation.
Sometimes you will operate in an environment where the organization has reached a high Level of Power Platform and Low Code Adoption. In this case you may notice that the need to manually produce documentation is limited, as there are processes and (technical) measures in place to (automatically) generate the documentation that is deemed relevant. In these organizations often there also is a streamlined Change management process that stimulates innovation through the application of Low Code Development and Hyperautomation. Therefore, organization-wide communication and collaboration are part of the organization’s culture. Involving the relevant stakeholders from Solution Ideation to Solution Delivery, is embedded in the organization’s DNA. This eliminates the need to produce comprehensive documentation every step of the way. More importantly, these types of organizations understand that it does not make sense to produce detailed documentation for Solutions that are constantly adapted. In these kinds of situations less effort should be invested in documentation.
- Document stable concepts, not speculative ideas.
Something I have noticed quite often is the amount of time organizations spent to document requirements in detail. Sometimes it just does not make sense, as – PMI states – requirements have the tendency to change. This is especially the case in environments with a high degree of Agility. Sadly, this is also the case in organizations which have not (yet) formulated a clear Low Code Strategy. This results in a situation that every week requirements change, due to the lack of common guidance. Please note that Agility is not equal to Chaos. Agility means a high level of adaptability, but with a predefined and agreed upon baseline in place. A classic example is the now discontinued Volkswagen Beetle. Through the years it changed its appearance as it adapted to modern times, but the foundation stayed the same. Okay, maybe that is a somewhat bad example, considering that it is now discontinued. But you get the idea, hopefully?
Other speculative ideas that are senseless to document in a comprehensive manner are wireframes, mock-ups, brainstorm sessions, and so on. These are just products that help to reach an agreed upon baseline. Once that baseline is defined, the rules, expectations and behaviors will be formulated that everyone will need to adhere to. That baseline, the associated rules and so on is called a Blueprint. This blueprint is the perfect candidate for comprehensive documentation. As I already mentioned in a previous blog post, I will dedicate a blog post on this topic in the future.
- Find better ways to communicate.
This is an easy one. Sometimes picking up the phone – or in this era of endless communication possibilities – starting a video call is more effective than a document requiring countless hours of reading. The latter is especially the case for Agile driven organizations. Studies have shown that face-to-face communication is still the most effective conversation and information sharing method. To determine ‘To document or Not to document’, think of factors such as expectations in regard to effectiveness, persistency requirements, geographical distance and physical presence. These are not my ideas, but originate from … you guessed it: PMI! You can find out more via this article where communication strategies are compared between people.
- Recognize that you need some documentation.
This blog post is all about the sense or nonsense about Documentation. So, I will leave this one as it is. I do want to provide a handy resource however for those that are interested in learning more about Agile and Lean documentation strategies. You can find that information via this link.
- Work closely with stakeholders.
In the end it all comes down to your audience. Who is the audience of the documentation? Is it Power Platform and Low Code Developers? Is it Business Stakeholders? Or will it be consumed by Business Users? Different audiences require different approaches.
In the case of Power Platform Developers, you can make use of Documentation capabilities that the technology platform offers, such as Code Commenting, Solution Notes, Azure DevOps Wiki functionality, Microsoft SharePoint, or third-party alternatives such as Atlassian Confluence, etcetera.
For other target audiences the answer is a typical one, which is well-known in the IT world: “It depends”. To make the best choice, you will need to understand how your target audience will consume the information. To measure the effectiveness of documentation, you can use the CRUFT formula. As PMI states: “note that 4 of the 5 factors rely on the customer of the document”.
And with this I have come to the end of this Blog post. Hopefully it will help you in the right direction when it comes to determining your Agile Documentation Strategy. Until next time!
Comments are closed