Written by Nincolle Graver

Where Is The Documentation?

If you work in the IT field, you have heard it more than once, and likely said it yourself…where is the documentation?  In the fast-paced world of information technology, documentation is usually one of the lowest priorities and tends to be overlooked until an issue arises. Then suddenly the team is scrambling to understand what has been done, why it was done and who approved this change.  In an Agile Development environment, clear documentation is vital for successful Agile implementations.  This blog will touch on an example of the type of issues that may arise and how having key pieces of documentation could have resolved those issues and why documentation is crucial to successful Agile implementations. 

Imagine…you are just a week away from kicking off a high-profile and publicly visible data collection project.  Though the custom-built solution has been operable for several years, there have been a few recent changes.  Your team is doing a run through of the system to make sure everything is ready for the project to kickoff. Hold on…the data being entered isn’t being saved to the database which in turn means that the workflows necessary to process the data will also not work.  NOT GOOD!!  So, what do you do? Typically, the first thing you will do is look back at what changes have recently been made to troubleshoot whether one of those changes may be your culprit.  What?  There is no documentation on the recent changes and no one on the team can recall precisely what changes were made?  You and your team are now in crisis mode looking at the system and its code trying to figure out what in the world may have broken. 

While it is true that the second manifesto of Agile is: Working Software Over Comprehensive Documentation that does not mean that documentation is not needed.   Instead, it means that the documentation should be minimal but useful.  Let’s look at how documenting in any, or all, of the phases of Agile Development could help identify the cause of the current problem.   

In the Agile world, user stories are your requirements for any new functionality or system changes that are being requested.  Therefore, the starting point of any change should be a user story.  Having incomplete or unclear user stories leads to frustration for the developers and the end users alike and can lead to disagreement between the two groups.  Additionally, it is just as important to update a user story when a change has been made.  This allows other members of the team to become aware of how the user story has evolved.  Clearly documented, but short and concise, user stories help the developer  understand what has been done in previous iterations and why it was made.

Change Can Be Good

So how does this help our team currently troubleshooting the issue with the system?  Having a documented user story will provide the team with what changes to the interface had been made and if any workflows were modified as part of the requested change.  This helps point the team to the appropriate section or components of the system to start their investigation.  One thing to keep in mind is that even those small changes or “tweaks” can have a substantial impact on the system and without any documentation, troubleshooting becomes very difficult.  All system changes, whether they are new requests, system updates or system fixes, should always be documented as if it is a larger request.  By documenting the full user story, you are ensuring that everyone has the same understanding of the request, why it is being made as well as allowing everyone to see the change to confirm that the change will not have a negative impact on other parts of the system or application.  Key to this is ensuring that the entire team is aware of how to write a good user story and where these user stories should be maintained.    It should also be understood across both the development team and the client is that no changes will be made to the system if there is no user story behind it.  Let’s assume that the product owner, through the established sprint planning process, has approved a user story to update the user interface to capture some additional information that will require verification through another system. The user story has been turned over to the developer who is able to understand all the specific things that are being requested of the system to capture and what should happen with the data once it has been submitted.  It will be essential to understanding how these two systems will speak to each other.   

To help ensure successful information technology projects and environments, ideally there would be an established change management process in place that everyone is well aware of and understands.  As part of this process, an outline of what is required to have prior to any deployment being approved should be created.  This includes things like code review, architectural diagrams, network diagrams, client approval, etc.  Because these will be part of the established processes, all members of the team will be well aware of what the expectations are and can include documentation and review time into their user story estimates.  Having quality code with appropriate comments is one of the most critical pieces of documentation and will provide valuable insight to future developers when either troubleshooting or making changes to the code in the future.  Basic network and architecture documents are critical but are necessary only when the change being implemented will have an effect on the existing diagrams.  Again, these do not need to be elaborate.  They should be just enough that anyone referring to the documents will find them useful in understanding the current setup.  In our example, there was a change to the application that required it to connect to another system for the verification of data and then return that data.  Because we have an established change approval process, our development team would not have been allowed to deploy their change without either creating or updating the existing network diagram.  Our troubleshooting team can go back to this document to see where there might be a possible break in the connection and where they should be pointing rather than taking guesses.  Failure to properly document your servers, databases, network architecture and over system information will force the technical team who is troubleshooting a system issue to spend valuable time researching these critical components to see where a change may have been made or where a change in another part of your infrastructure may have an impact on other parts of the system.

Working Software Over Comprehensive Documentation   

So, while these various forms of documentation are often very time consuming to create and maintain, they are critical aspects of any information technology project even when using an Agile methodology.  The second manifesto of Agile is:  Working Software Over Comprehensive Documentation.  The intent of this strategy is not to eliminate documentation, but rather to streamline it to still provide the information necessary for the successful implementation and support of the software and/or system while not requiring an exorbitant amount of time and effort in creating extensive, and sometimes excessive, documentation.   In their Core Practices for Agile/Lean Documentation, Agile Modeling points out that having extensive documentation does not ensure project success but instead, the team should focus on concise and accurate documentation over detailed documentation that is likely to have errors in it.  The key to obtaining adequate documentation is ensuring the team has reached a consensus on what will be required throughout the Agile approach.  This includes the format and expected content for a user story, the documentation that should be created and submitted when a change is submitted for approval and the expectations for configuration management.  Failure to agree on the expectations will lead to inconsistent results that are unreliable and often incomplete. 

Now Let’s Return To Our Example From Earlier…

What is preventing our data from being saved to the database?  Because we had a good user story documented and our technical documentation was current, our troubleshooting team was able to quickly identify that the user story required that the system first verify the information before saving the data to the database.  Due to a firewall change, our system was not able to communicate to the database to make this verification.  With some assistance from the firewall team, we were able to quickly make the change and data is flowing as expected and we are ready for the kick off the data gathering project as planned! 

Is your team struggling with how to document efficiently in Agile?  Need help identifying where your documentation might be lacking?  Contact Momentum to see how our team of experienced Project Managers, Business Analysts, and Change Practitioners can help! 

References: 

“Core Practices for Agile/Lean Documentation”

www.agilemodeling.com/essays/agileDocumentationBestPractices.htm#JustSimpleEnough  

“Agile/Lean Documentation: Strategies for Agile Software Development” 

http://www.agilemodeling.com/essays/agileDocumentation.htm#WhenIsADocumentAgile 

                                          Nincolle Graver – Consultant

Nincolle Graver is a veteran Project Manager with over ten years of experience in managing IT projects for various public-sector clients and assisting Project Management Offices (PMOs) with the transition from Waterfall development methodology to Agile development methodology.  She maintains a high-level of business process reengineering and change management expertise to help organizations successfully complete projects and implementations. She is certified in ITIL, Scrum Foundations, and has earned her Six Sigma Yellow Belt.