How Do You Decide if Project Documentation is a Need or “Nice to Have”?
As a project gets started, a question that always comes up is “What level of documentation do we need?” I know from experience that the further you dive in, the easier it is to let the project documentation slide. As you have deadlines to meet and additional scope slipping in it’s easy to focus just on getting the work done and thinking “I’ll get to the documentation later.” However, I also know from experience that “later” very rarely comes and the documentation that was skipped over never gets created or updated.
So the question is – how necessary is documentation? If you skip some of the documentation, does that really affect your implementation? There are a lot of successful implementations that haven’t documented 100% of the designs, changes, and decisions. However, I've experienced that skipping the documentation can cause quite a few problems.
Missing & obsolete documentation situations during implementations:
Reviewing decisions
Multiple discussions/meetings occur to re-cover decisions that were made previously. This usually occurs because another scenario comes up that causes questions to arise about why the process was designed a certain way or why certain configurations were chosen. It requires all options to be rediscovered and then discussed before usually arriving at the same decision.
Configurations are changed
Configurations are changed to accommodate a new requirement or process and all the sudden other processes aren’t working as planned. If the configuration is documented, it’s easier to know why it’s set up a certain way and what will be affected if it’s changed.
Scope of a modification has changed
Extra testing, rework, and discussions with developers are required when the scope of a modification is changed and the initial design document is never updated. Once you get to testing and are trying to reference the design to make sure you are testing everything, you run into situations where the solution doesn’t match the design. This causes a lot of confusion and a need to work with the developer and the people who designed it originally to determine if it’s not working the same because it’s a bug or because there were undocumented changes.
Keeping the team informed
Bringing other people up to speed on the implementation is more haphazard and more work. Whether it’s adding someone to the implementation team or just training users on the implementation, you have to bring them up to speed by memory and a lot of pieces are easily missed. While the basic processes are usually easy to remember, it’s sometimes difficult to communicate why certain pieces of the process are so important or why it was set up in a certain way. Also, if you are wanting users to take more ownership of their areas of the system and be less dependent on the original implementation team, it is a lot easier for them to do this if there is complete and accurate documentation for them to reference.
Lack of documentation for the future
Aside from the situations I mentioned above, the other impact that is usually forgotten about is the impact lack of documentation has on future implementations, upgrades, or even simple changes. While you are in the middle of your implementation it’s hard to imagine ever forgetting major designs and decisions, but the more time that passes the more details are forgotten and the more likely it is that original implementation team members have moved on.
Upgrading or changing custom features
When you want to upgrade a custom feature or even make some tweaks to it, if there isn’t any design and/or development documentation for that feature it takes a lot of time digging into the code to figure out exactly what the feature is doing before any changes can be made to it.
Changing business processes
When you want to change some of your business processes, there is a great risk that you will go down a path that the original implementation team had a good reason for avoiding. You could end up spending a lot of time trying to figure out why the original decisions were made and what issues you might run into by changing them.
Adding a new feature
When you want to add a new feature you could inadvertently break a previously developed feature. Without having the documentation for that feature, it’s hard to know exactly how it was developed originally and what changes could affect it.
Decision to document depends on many factors
Now you may be wondering – does this mean I have to spend hundreds (or even thousands) of hours documenting every little piece of the implementation? Unfortunately, there isn’t a very clear answer to this. It really depends on many factors including the size of your implementation, the budget and timeline for your implementation, and the number of people involved among many other things. You will have to determine for your implementation and your organization what the right level of documentation is.
What to consider when deciding on project documentation:
Is it something that affects a major part of your business?
Usually, there are some core business processes that, if they aren’t functioning right, can greatly impact your ability to do business. It is highly recommended that anything related to those core business processes be documented.
Are there multiple people working on this process/piece of functionality?
The more people that are working together, the higher the need for documentation to make sure everyone stays on the same page.
Is it a complex process or feature?
If it’s complex with a lot of moving parts, it’s important to document how all the pieces work together.
Is it a process within an area of your business that sees high turnover?
If you have high turnover in an area of your business and people are coming and going fairly frequently, it is important to make sure processes within that area are clearly defined and documented.
Are there planned changes or upgrades for this area?
If you are planning a future phase which will add more functionality or improve on the existing functionality, it’s important to have clear documentation around the processes and features that will be modified at a later date.
Project documentation recommendations
We recommend that you decide at the beginning of your project what level of documentation is necessary and then be sure to add time to complete that documentation into your budget and timeline. The important thing to remember is that the cost and time you save by not documenting something could end up being consumed many times over later down the road because you don’t have that documentation.
Under the terms of this license, you are authorized to share and redistribute the content across various mediums, subject to adherence to the specified conditions: you must provide proper attribution to Stoneridge as the original creator in a manner that does not imply their endorsement of your use, the material is to be utilized solely for non-commercial purposes, and alterations, modifications, or derivative works based on the original material are strictly prohibited.
Responsibility rests with the licensee to ensure that their use of the material does not violate any other rights.