Yesterday I presented a case at a“KM Challenges” workshop, jointly hosted by the Boston Knowledge Management Forum and the Boston chapter of the Special Libraries Association.
My session concerned the documentation that is created to support the implementation of technology solutions. As the system is designed, launched, and then evolves, how do you keep the documentation (whether it be requirements, technical design, site maps, relationship diagrams, physical / logical architecture models, details about customizations, etc.) in sync with the current state of the environment or the current policies in place? There are many compelling reasons to do this, however most of the organizations I work with don’t have a system for handling it. As a consultant who delivers SharePoint projects and the documentation to support them, the ongoing maintenance of that documentation is typically out of my hands, but I want to help my clients avoid the issues that out-of-date documentation can cause.
The cases I outlined were variations on the same theme, as follows:
1. In the design of a new technology system, requirements documentation and a technical design spec is written, approved, and signed. When the design phase ends and the construction phase proceeds, the scope often changes during the build; however nobody goes back to update the written requirements. The risks inherent in this situation: if there is a dispute over what was built, there is no way to reference the most recent approved version of the requirements or spec.
2. To provide policy and oversight for the new system, governance documentation is written. As time passes, the system evolves and policies change. (Examples: a new version of the system is launched which includes the ability to rate and freely tag documents; a collaboration area is created where all users have the permission to create new sites) Nobody goes back and updates the governance. The risks inherent in this situation: if policies are not put in place, uncontrolled growth or sprawl could occur. Staff members could use the system in unapproved ways, which is more difficult to stop/enforce without a policy.
3. After the technology system is launched, updates are made over time. (Examples: the system administrator installs a third-party web part; a power user creates a custom workflow) These changes are not documented. The risks inherent in this situation: In a disaster recovery scenario, the system cannot be fully restored. If the system was built by an individual who leaves the company or a vendor who goes out of business, there may be nobody at the company who knows how to make changes to the system without breaking it. The changes that are made may have downstream consequences to other users, who may spend hours trying to figure out what affected their piece of the system.
4. In an organization without a robust Help Desk / ticketing system, the IT staff may be too busy to document the issues they resolve or the changes they make. Knowledge is kept in the heads of the staff, and to some extent in email. As time passes and the staff turns over, the same issues might be encountered again and again without any way to connect them. The risks inherent in this situation: Different staff develop their own ways of handling issues; the lack of standards creates confusion. Time to resolution isn’t shortened by having a common knowledge base, which can lead to frustrated users.
I had the benefit of fourteen intelligent, experienced minds to help me brainstorm solutions to these problems. Three hour-long sessions, each one with a different team workshopping the same four cases, produced a long list of suggestions. These boiled down to about 20 unique suggestions which sorted into five major categories:
Make the case
Make a compelling argument to the organization that emphasizes the reasons why they should protect their investment by keeping documentation up to date.
Share the negative - relate anecdotes of disasters and consequences, discuss downstream consequences of each system change to the other users in the system, provide hard numbers around costs. What is the cost for a vendor to come in and document all the undocumented? What is the cost of the application if it has to be rebuilt?
Share the positive - show the ROI of documenting, tell success stories – i.e. businesses or individuals who saved money, averted disaster, reduced the occurrence of issues or time to resolve them.
Schedule it – build in time to review changes and document them. Hold monthly or quarterly meetings with the team to discuss and document any changes that have been made to the system. If working with an outside consultant, make this recurring review/documentation part of the maintenance agreement with that vendor.
Leverage the training/orientation process; let training documentation serve as system or governance documentation. (Typically there is a strong focus on keeping Training documentation up to date, because it is highly visible and training occurs on a regular basis.)
Add a loop-back step at the end of each phase to check whether requirements, design spec, diagrams, etc. need to be updated. What are the gaps and how will we handle them?
Give a role to new hires to document changes, create knowledge base articles. As one of my session attendees said, “The newest person there is like your customer.”
Find the right resource – acknowledge that not everyone has an aptitude/affinity for documentation, and find / hire / outsource to someone who does.
If the system administrator is too busy to document as he/she goes, assign a scribe who can shadow, take notes, document.
Write or expand a job description, e.g. “This person needs to document this this and this. It needs to be done with this frequency. These tools will be used.”
Change the Culture
Screen new hires around code quality or documentation ability. If a candidate is going to be expected to create documentation as part of their role, make this part of the interview process.
Change the management style – instead of implementing requests as soon as they are made, institute a policy that for a certain period of time, the system is frozen, and frozen means FROZEN. Limit firefighting by asking, "Can it wait?" Roll requests into packages of changes rather than making them ad hoc.
Institute change review / code review, and require that more than 1 person is required to make a change or close a ticket. (This can also be a training tool for junior staff / new hires.)
Document at the front end rather than the back end – any time a change is requested, get signoff on the current state & requested changes, and document the request first before the change is made.
Make the change process more collaborative – have code review, hold meetings to work out large requests, let requestors negotiate priority among themselves; in essence, have more conversation around change rather than top-down “just do it, and it must be done immediately.”
Use / Improve tools
Make it easier for documenters to take screen shots, do voice recordings or video capture of steps taken.
Provide a template for updates and changes rather than an open-ended “comments” field where users might not be sure what they should write.
Provide a system to track requests, prioritize them, and add details about what was done.
Find out whether an automatic audit log can be implemented.
Leverage analytics and data mining to determine where efforts should be focused. What are the recurring issues that are most important to document? How many times was this KB article viewed (by customer, by IT staff)? How well is it rated?
We’re overcoming human nature here so there’s no easy solution. The situation can’t be solved unless organizations recognize the value of investing in up-to-date documentation – and in many cases, it’s human nature not to recognize the value until it’s too late and the disaster actually happens. But there are many ways that organizations can improve what they do today. I hope that one or more of the ideas above will be helpful to your organization.
Literate Programming - Software Documentation - a collection of brief quotes and ideas about the importance of software documentation from a variety of sources
Neglecting Systems Documentation Courts Disaster - discusses scenarios, consequences, and types of documentation.
89 benefits of documentation - some high-level ideas that could be used to develop R.O.I. estimates