Author: Larry Blankenship

When to Document in Agile Projects

Written by Larry Blankenship on February 12, 2020. Posted in Articles. 5 Comments on When to Document in Agile Projects

One of the planks of the Agile Manifesto states, “We value working software over comprehensive documentation.”

Unfortunately, people working on the project take this to mean that working software is sufficient and there is no need for any documentation. This could not be further from the truth. What do you need to document? In this article, I’m going to give you some suggestions for deciding what needs to be documented outside of the comments in the software (and yes, commenting your code is still useful as long as you focus on what and why, not how), and what got captured in in the ticketing or project management tool.

There are three places where you can create the most value when doing documentation outside the ticketing system:

Tracking Decision Making
Meta Data about the Project
Process Integration

Tracking Decision Making

Typically, tracking of decisions that the team made in each story happens in the Project Management System or in a system like JIRA or TFS. However, there are times where it will be useful to have a summary that captures the major decisions, who made them and why. This can come in handy during the maintenance process where knowing why the team made a specific design decision may be the difference between changing a variable and rewriting a whole section of code when a change is required.

It can also be helpful during reviews and project post mortems when it can be essential for capturing lessons learned during a particular sprint. A simple way to approach this is to use a list in Sharepoint or an Excel spreadsheet with the following headings:

Release
Sprint
Description of the issue
Summary of Discussion
Decision Made
Effect of Decision

Metadata About The Project

Often, much of the information about the application will be self-contained, which is perfectly good as long as you have the hood up and can get at the wires underneath with ease. There will be times however, that having the application be a black box is going to cause issues for people who work on the application later. Even though applications are supposed to be black boxes, it’s good to keep notes on where the keys are so if you need to unlock the box later, you can.

Information that can be helpful in this instance includes:

When the application went into production
Location of the source code
Location on the network where the production application is located
Database connections or at least which database contains the application data
Business Owner – Who has the authority to make decisions about the application?
External Web Services or FTP servers that are used and any credentials needed (We store credentials in a central password vault)
Any coding standards used (this can be very useful when the work is being done by contractors who may not be available for maintenance work).
Any off the shelf applications that may be part of the system. This can be especially important when the off the shelf application gets an upgrade or has the version in use deprecated.

Advertisement
[widget id=”custom_html-68″]

Process Integration

I am a big fan of process documentation. As one mentor told me, “If it’s not documented, it’s not a process, it’s a regularly occurring event.” ISO-9000, one of the most popular quality standards devotes several clauses to documentation. Process documentation provides a record of the baseline of your process, which you can then use to monitor changes and how well those changes worked.

When dealing with a new system, I like to know how the user will do the process with that system, not just how the system works. When I’ve taught software classes in the past, I’ve focused on a task and how to use the tool to perform that task rather than just how to use the tool. For example, when I taught Powerpoint, I taught how to create effective presentations using Powerpoint, rather than just teaching Powerpoint.

I personally prefer to use flowcharts for process documentation, but depending on your industry and regulations, you may have to write something more formal. The most important things to document when writing process integration documentation are:

What job title does the process?
How many people do the process (useful later when prioritizing trouble tickets)?
Can the process still be done manually or via a work around if the application isn’t working?
What are the inputs and outputs for the process?
Are there feedback loops to let the person who created the input or output whether there was an issue?
What is the value created by the process and how does the software contribute (this is something that you probably did during the requirements phase, but it’s good to go back and review to make sure something didn’t change in the meantime.)?
Keeping some kind of history of changes and so forth can also be very helpful.

How Much is Too Much

One of the reasons that working software is valued more than comprehensive documentation is that comprehensive documentation is a huge consumer of project resources, both in creating the documentation, and in maintaining it. Massive quantities of documentation can result in binders full of information that no one will actually end up reading, or that will be out of date almost immediately. Keeping documentation at a useful level is very similar to writing user stories for a software project.

As a Developer

I need to be able to easily find metadata about an application

So that I can start working on maintenance tasks immediately when asked

As a Project Manager

I need to be able to see a history of decisions made about a project

So that I can improve the decision making process

As a User

I need instructions that show me how to do my job with the application

So that I can be productive immediately and reduce my learning curve

Albert Einstein addressed documentation and software design when he said “Everything should be made as simple as possible, but no simpler.” Understanding the value of what you document will help you do just that.

You’ve Got Processes With A Capital P and That Stands For Trouble!

Written by Larry Blankenship on April 30, 2019. Posted in Articles. 7 Comments on You’ve Got Processes With A Capital P and That Stands For Trouble!

In Meredith Wilson’s “The Music Man” there is a scene where Harold Hill, the conman,

attempts to alarm the people of River City about the local pool hall to get them to buy band instruments. The refrain is “You got trouble my friends, trouble with a capital T which rhymes with P and that stands for pool!”

I’m going to turn that around and tell you that you may have processes with a capital P and that rhymes with T and that stands for trouble. When processes become Processes with a capital P, it means that they have stopped being a means to an end and have become the end themselves. They have become enshrined, which is the term I’ll use in the rest of this article. This can get to the point that they impede continuous improvement because the people who do them are emotionally invested in them. This sometimes leads to resistance to change when change is badly needed.

That is not to say processes aren’t needed, only that they should act as a support to achieving desired outcomes, not become the desired outcome. Doing things in a consistent way, using a process, is the most effective way to experiment with changes and understand what worked and what didn’t, but it can become a trap, if the end result isn’t kept in mind.

The first identifier for an enshrined process is its overabundance of documentation. Typically, this involves multiple volumes of manuals, protected by a complicated and byzantine approval process. Any change requires a thorough review by several committees and multiple sign offs, by which time the requirements for the change will have become out of date, and all involved will throw up their hands and claim that the whole process is too hard but won’t do anything to fix that either.

Another sign of an enshrined process is knowledge hoarding. If you find that only one or two people have full knowledge of how things work, and they jealously guard the information, it’s probably a good candidate for an enshrined process. In this instance, there will be very little documentation to enable others to evaluate or analyze the process. SMEs will be reluctant to share or will frequently claim that things are “too complicated” to explain to someone else.

If the work has become more important than the outcomes it produces, then you have encountered an enshrined process. Look at the metrics used to measure the process success. Do they relate to business objectives, or are they measurements of execution? Number of complaints processed with a goal that goes up is a process measurement. Number of customers rating their customer service experience as a 4 or better on a 5 point scale measures a business objective of satisfied customers.

Once you’ve identified an enshrined process, what to do about it? The most critical element in this case isn’t the business, but the people in it. I want to share a couple of techniques I’ve found useful in the past: Acknowledging concerns, and involvement in the solution.

Advertisement
[widget id=”custom_html-68″]

When acknowledging concerns, the pattern I’ve learned to use is Feel-Felt-Found. I learned this during my sales career. Start by acknowledging the person’s concerns are legitimate by saying “I know how you feel, many of the people I talk to felt the same way about changing how they work.” Then reassure them with other people’s experiences. “People who’ve been through this process have found that it really made things work better. Can we give it a try?”

Involvement in the solution is the best way to build ownership in the new process and prevent people from subverting change by passively or actively resisting it. If you’ve done your job in carefully listening to the people doing the process, and gathering their input, they will feel a sense of ownership in the new process. The important thing is that they will feel that they improved the process rather than had the changes imposed on them.

Assuming you’ve managed to successfully implement a new process, how do you prevent it from becoming enshrined all over again? It’s easy to assume that the hard work is over, but if you fail to plan for changes to the contexts the process operates within, it’s possible that the next change will require you to start from the beginning rather than make another incremental change. Your first objective is to make sure that you don’t rest on your laurels.

If you’ve taken time during your process review and rework to incorporate a continuous improvement culture, then much of your work is already done, as people will already be thinking about how to review and rework the process on a regular basis. If not, take the time now to set up regular reviews and identify metrics that will allow you to validate that the process is achieving its desired objectives. Make sure that you focus on business objectives, not process objectives. If business objectives aren’t being met, adjust and try again. The most important thing is to avoid falling into the same trap of measuring the process not the outcome.

The second objective to strive for is to make change easy. Keep feedback loops in place to allow the people who provide inputs information on how to improve the quality and usability of those inputs. Make sure that any feedback provided from the people who receive the output is reviewed and acted on a regular basis. Try as much as possible to use a “black box” approach. That means that the people outside the process don’t necessarily have to know the details of how the process works, just that it produces consistent, predictable results. Keep your processes as independent as possible to minimize the impact of changes on other business areas when changes are required.

The final objective is to keep documentation simple and readily available. At all times, the current version of the process documentation should be online and available to everyone who performs the process. Sharepoint or an online wiki are great places to keep shared documentation. While it’s important to have version control, it doesn’t hurt to make the documentation easy to change when it’s needed. Focus on pictures and short paragraphs. Avoid writing novels. Flowcharts are one of the best ways to describe processes. Keeping the documentation simple means it’s less likely to end up in a paper copy on someone’s desk, which means it’s out of date by definition.

I hope by following the suggestions in this article, you’ll be able to recognize, fix, and avoid enshrined processes in your projects. I think you’ll find the benefits of doing so are substantial.