Documentation – To Be or not To Be

Posted by at 11:22h

Once upon a time, development world lived and breathed Waterfall. Back then, Requirements, Test Plans and Release Notes were more important than the product itself. This time is no more. We live in the world where the end product is the goal and process is just the means of getting there. Documentation is a nice to have which often gets overlooked in the world of Agile delivery. In an ideal Agile and DevOps scenario, all requirements are recorded as User Stories, test cases are expressed in form of Acceptance Criteria and Release Notes can be generated automatically in Jenkins from the integrated Source Control system. However in reality, it is rarely the case.DocumentStuff

The best way to decide what should and not be documented is by applying the Bus factor formula. If it only takes for one Developer/QA engineer/Business Owner/DevOps engineer to not be there, for the project to halt (Bus factor of 1),  then there is a definite requirement for good documentation in that area. In case of Developers, items like Backend and Frontend architecture, Database ER diagram, technology stack, analysis and decisions behind the selected tools, API flow, etc, need to be well documented and reviewed. For QA, Test plans, test cases, Release Notes are very important and not having them written down will result in additional work and increased quality risk down the line. Having requirements well documented whether in JIRA, Quality Center or word document, will not only help Business Owners but also Developers and Testers to reduce ambiguity in business functionality.

While this might not seem very challenging for a new development project, it is a lot more complex for an existing product that has been in production for a while and went thru multiple releases and bug fixes. Manual documentation exercise in such scenario might not only be overly complex but often impossible.  Introducing custom scripts that keep log of all API calls can significantly help in mapping the API workflow. One of the most challenging but yet necessary tasks is documenting the Database structure and relationships for complex products which in many cases connect to multiple database systems.   This would be an impossible undertaking if it wasn’t for Data Management tools with Discovery mechanism that allows to scan existing data systems, discover upstream and downstream relations and visually represent the data flows.

Combining these tools and strategies together with strong management support can really move the products and the company to the next level of continuous learning and improvement.

To learn more about Data and Transformation solutions visit

Click here to download ROKITT Astra white paper