Connecting the Dots: from Technical Design to Documentation

Designing software can often involve napkin sketches, sticky notes, and whiteboarding to initially explore, visualize, and communicate an idea. So, what’s next? Creating a technical design document seems to be a no-brainer. But what really requires some brain activity is how to make it happen. This is a common challenge that many companies and individuals have faced and written about, here are some good examples:

• A practical guide to writing technical specs
• How to write a better technical design document
• How to write a good software design doc.

However, we quickly realize that there is no silver bullet to effective documentation, for example how should the developer’s setup, workflow, and visualizations be married and expressed to readers without creating a confusing mess? A document might be really well structured, but readers won’t necessarily be able to grasp the entire picture.

Also, how do we deal with the fact that a design document might become obsolete after release if it’s not kept up to date? How do we ensure what may be documented or self-documented in code complements what is in the technical design document? And finally, how can it be turned into a useful reference, ideally for the long term?

In this article, I’d like to share a bit about how we have tackled these problems in our group at Lifion, by ADP.

A developer’s experience of documentation

As a developer, I imagine in the past while ploughing through somebody else’s design doc you may have ended up scratching your head once or twice.

Not all documents are created equal

When new to a team, it’s not uncommon to spend much time reading documentation, trying to relate it to and understand the relevant code base. And depending on the author and level of organizational standards, documents can vary sometimes quite substantially. So we are sometimes forced to start not with understanding the actual feature in question, but with the structure of the document itself.

Recursive context-switching

Gaps in the design can lead us to jump back and forth between the code and a document (and even within the document itself!) Having fun?

You can’t step into the same river twice

Uh oh, it looks like the code had diverged from the design document since it was written! And maybe even the person who wrote the code or document has left the company… Now is the time to hone Git skills because we will be going commit by commit to understand the design intentions and how to work with the code.

Rube Goldberg machine?

OK, I got the idea of the code, how do I start working with it? The next step is to build your own developer setup. What are the steps? What components do I have to set up and how?

‘I would do things differently’ — one might say after figuring everything out. But when writing a document, without noticing it can be easy for anyone to fall into the same pitfalls.

One doc to rule them all

Now when we have clearly identified the list of grievances, we can define some guidelines for our design documents:

• Use the same structure and tools for all documents
• Provide a visual representation of the developer setup: all prerequisites and their settings needed to start the development
• A consumer of the design document should be able to understand its logic without examining the code
• More images, less code snippets
• Any subsequent changes should be reflected in the document

Use the same structure and tools for all documents

Having all documents adhere to the same structure and be developed using the same tooling gradually shortens the time it takes for a reader to understand the document’s essence. As an example, some structure we try to follow:

I. Overview of the existing behavior

Show the area(s) where your changes are to take place, completed with the current wireframes. For example:

II. Use cases

Provide a full list of use cases, use wireframes to display the workflow from the user’s standpoint

III. Updates to prerequisites and their settings

Clearly depict (possibly using mockups) updates that are required for a development environment

IV. Workflow

The heart and most complicated part of the design document. The goal is to put together a diagram that describes the new process with the changes clearly indicated.

The diagram might include a limited number of snippets to show the key data structures, their usage, and impact on the visualization.

Aim to use the same flowchart-generation software across the board (diagrams.net, formerly draw.io is a good example.) Compile and share a vocabulary of the visual elements, for example:

• all affected code areas

• all changes

Where appropriate, make your diagram interactive. A reader should if possible be able to collapse or expand components. This will make the diagram multi-faceted, allowing consumers to focus on specific paths and details of interest:

V. Conclusion

Use this section to list the proposed changes; when a planned feature is broken into work items with corresponding implementation tickets, the links can be pasted here, for example:

Provide a visual representation of the prerequisite settings

If the new feature requires changes in the developer’s setup (in I. above) the readers of a document will be thankful for the images on top of the written instructions.

A consumer of the design document should be able to understand its logic without examining the code

No more jumping between the document and the code: the workflow diagrams in the design document should be clear and concise, eliminating the need to examine the code base. Use your peers as reviewers: they will point out the gaps and the areas that are not clear enough.

More images, less code snippets

It’s important to assume that a document will likely be used as a reference by new team members when working with a given code base. Ideally, they should be able to follow it image by image to learn, get set up, and be productive with the code. It is up to the writer to make it as easy as possible to understand.

I typically recommend that code snippets be used only if absolutely necessary as they can be harder to understand for some, employ flowcharts instead.

Subsequent changes should be reflected in the document

This is probably the most important bullet point. The evolution of a design document does not end when it is approved for development:

• there might (and most likely will) be gaps discovered during the implementation stage
• when development is complete, there might/will be updates in the same area to accommodate new features or fix bugs

A simple rule can help keep a design document up to date. A developer that is responsible for a given code change must update the design document: no pull request should be merged otherwise.

This rule can help turn a technical design document into a reference document.

Conclusion

Large projects can suffer greatly from a lack or inconsistency of documentation. Impacts can include a longer learning curve for new team members, regression issues caused by outdated specifications and as a result, unnecessary increased project and ongoing costs.

Bridging the gap between technical design and well-maintained documentation is one of the ways to help bring delivery costs down while significantly improving developer productivity and experience.

What has been your experience regarding technical documentation and what approaches have you seen work well? If you’re working on or are interested in solving similar challenges then let’s connect, we’d love to hear from you!