Creating a developer documentation workflow

Today’s popular software development model is DevOps, which is really about a relationship between developers and other IT staff. At its core, DevOps still relies on the same essential software development practices that have been used for decades - but with the added “spin” of working much more closely with others across different teams.

Some years ago, I managed an application development team. If you manage a similar team, you may know that developers aren’t always fond of writing documentation. Many of the developers I worked with would rather focus on the fun part of coding. One common refrain to avoid writing documention was “good code documents itself.”

I found that creating a framework or road map for generating documention helped keep my teams on track. It was a happy “middle ground” for my developers and others who needed to migrate their projects from the “Development” instance to the “Test” instance, and later the “Production” instance. At a high level, we used five documentation milestones that would allow developers to “document as they go” and would grow with the project:

1. Statement or purpose
2. Options (similar to a “Design” document)
3. System diagram
4. Roles and responsibilities
5. Lessons learned

We defined each documentation milestone like this:

1. Statement or purpose

At the project’s initiation, we documented a high-level overview of the project. This was often created in partnership with the project team and the customer (my teams created systems for others in the organization, such as faculty and students when I served as an IT director or campus CIO in higher education).

The “Statement” document (sometimes called a “Purpose” document) captured several items, including:

• What is the problem being solved?
• Who are the stakeholders?
• Who are the decision makers?
• What is the scope?
• What is the timeframe?
• What are the deliverables?

For other versions of this document, we also might include other items such as:

• What technology best fits the design?
• Will we use Agile or Waterfall?
• How much involvement does the customer want?
• How are end users affected?

2. Options (similar to a “Design” document)

Before writing any code, the developers completed a separate document that highlighted items from the “Statement” document, and identify possible paths to work on. This “Options” document was similar to a “Design” document, but at a higher level, and identified decisions such as these:

• What possible solutions do we have, including pros and cons for each?
• What data sources do we have to work with?
• What can we re-use and what do we need to build?
• What environment (server) will this run in?
• What architecture (such as databases) do we need to connect to?

Depending on the project, developers might also address other questions, including:

• What monitoring system needs to watch the application?
• What do we need for disaster recovery planning? (Small projects that don’t make much of an impact may not need one.)
• What data policies (such as FERPA) apply to this system?

3. System diagram

While developers were creating the code, we also asked them to capture a high-level diagram that described how the application connected to other systems. For example, a web applicaiton might communicate with business logic servers or “app middleware” to do certain work, and/or communicate directly with a database for queries.

The goal with this diagram was to get an overview of the components of the system they were building, so the IT support teams could have things ready when the application moved from “Development” to “Test,” and then to “Production.” Usually, we looked for these items:

• What hardware is required?
• What software is needed?
• How does data flow between systems?
• What dependencies does this have with other systems?
• What other teams might need to get involved?

4. Roles and responsibilities

Before an application would be approved to move from the “Test” instance to the “Production” instance, we required the project team to document the roles and responsibilities of the new system. Our project managers usually took this responsibility, although it was often documented as part of the “Business Analysis” phase. This document answered the Who, What, Where, When and Why of the project, such as:

• Who provides support?
• Who manages the data?
• Who migrates the system into production?
• Where is the documentation stored?
• Who (which developer) is the key person for bug fixes?
• How does the customer request changes?

5. Lessons learned

After every release - whether successful or unsuccessful (but usually successful) - we paused to identify what went well during the project, and what we should do differently the next time we work on a similar project. We found the best way that worked for our teams was to have the key members of each team (developer team, application team, project management team) gather for a meeting where we listed the “Plus/Deltas” of the project. This whiteboard exercise usually took a half hour to an hour, and we usually gathered about two weeks after the project went live - far enough out that we had probably responded to any arising issues, but close enough that memories of the project were still “fresh.”

A road map to documentation

This five-step approach to creating documentation provided a good balance, for how we needed to build software. It provided a framework for creating the documentation. And by following that framework, we essentially provided our teams with a road map to documentation.