A software design description is a representation of a software design that is to be used for recording design information, addressing various design concerns, and communicating that information to the design’s stakeholders.

— Wikipedia1

Background

Design docs are a great way to communicate ideas, get feedback from your team and align on what to build.

They propose a solution to a problem and a set of requirements. Normally while the document has not reached a consensus, the project is blocked.

This article assumes the design doc itself is understandable by the audience, the problem it is trying to solve is well defined and the proposed solution is not controversial or extremely out-of-the-box/innovative.

Problem

Our objective when writing a design doc is to get feedback and alignment on the proposed design.

The problem we are trying to solve in this post is when the design doc does not provide us with this value once written.

There are a few reasons why this might happen:

  1. The document is not read
  2. The document is shared and read but it seems no decisions are made
  3. The document is full of non actionable feedback that questions the existence of the document in the first place.
  4. There is confusion on the decision reached.

We will try to address each of these issues and how to mitigate them in the following sections.

The document is not read

The document is written and shared but there’s no feedback or discussion.

Three issues can be at play here that can be fixed:

  • The document simply did not reach the reader.
  • The document was targeted at the wrong audience or it was not made clear why it matters to the reader.
  • There was not enough context provided to the reader to understand they should read it.

Who is the reader and how can I reach them?

The right people are the stakeholders of the project, anyone who might be affected by the design and anyone willing to provide feedback.

To get the document in front of the reader we need to consider distribution channels:

  • Direct message (email, slack, etc.)
  • Internal post (mailing list, public mattermost channel, etc.)

My goto is a post on the organization’s internal messaging platform (slack) in the channel dedicated to the project or the team’s/division’s channel if the project does not have a channel.

That post will include a link to the document and a short description of the problem and the proposed solution. Tag the stakeholders you know are directly involved in the project and have probably been awaiting the document.

If you are a direct stakeholder, you’ll probably want to be pinged if the document has been available for a while and you have not read it.

Don’t shy away from asking for feedback directly as it is in both parties interest.

Finally, if you work in a team, it can be useful to schedule a meeting to present the outline of the document and the problem it is trying to solve. This will lower the barrier to entry for the document and make it easier to get meaningful feedback.

It might be easier to do team feedback in a smaller & faster feedback loop as it will improve the document before it needs to be shared with other teams that are harder to reach. Your team members will then be also able to help answer questions from other stakeholders and brainstorm solutions.

You should emphasize that it’s ok for your team to answer questions on a document that is not theirs.

In my team we usually bundle this into a weekly meeting where we discuss ongoing design docs.

There is a final issue that was not mentioned: Maybe the document was read and the reader did not have anything to say. The advice in the next section covers these.

The document is shared and read but it seems no decisions are made

The document is written and shared, the actionable feedback has been incorporated and other stakeholders have read it but the document just sits there without closure.

You first need awareness of the document’s feedback state. The easiest way to solve this is to have readers leave a note or a reaction on the document to indicate they have read it.

This would fix the issue of knowing if the document has been acknowledged but it’s not always guaranteed that the reader will leave a note and if their lack of feedback is a tacit approval or an oversight.

As such you can set a deadline for document feedback. This makes it the reader’s responsibility to provide feedback in a timely manner and allows busy stakeholders to prioritize the documents they need to read.

Be mindful of the deadline you set. Everyone is busy.

This also allows readers to know if providing feedback is still relevant or if the document has been finalized.

There will be exceptions to this deadline in an environment where other team’s decisions directly impact your design. This will be very organization specific and how much autonomy you and your team have to take decisions.

Having a meeting with the document’s main stakeholders at the end of this deadline is a good way to finalize the consensus on the document and move on to the next step.

In my team we usually bundle this into a weekly meeting where we discuss ongoing design docs

The best problem to have is too much feedback. Unfortunately, sometimes this feedback is not actionable in the sense that it’s not actually related to the design proposed but rather to the problem itself.

This indicates there is an issue with the problem and requirements definition. Before writing the document, ensure the problem and the requirements are well defined and there is a consensus on them. Ideally you’ve built some level of initial organizational support/buy-in.

This can take the shape of a product requirements document (PRD)2 for product development or a software requirements specification (SRS)3.

On smaller projects, especially when the problem, requirements and design are at the responsibility of a single contributor, this can be done in the same document.

A good pattern to follow is to write a one page document of the problem and high level solution description, share it as it will be fast to read and then expand it to a full design document, this is especially relevant if your organization does not have a PRD/SRS process. This also allows you to catch any potential issues early on that would require a full rewrite of the document.

There is confusion on the decision reached

A design document in a fast moving organization is a living document, from the moment it is written it is outdated.

As discussed in the previous section, once feedback is collected and consensus is reached, asynchronously or in a meeting, the document should be updated to reflect the consensus.

Normally, a section called “Consensus” is helpful even if it indicates that there are no open questions on the document.

If design docs are used as decision logs in your team, add new dated sections to the document instead of editing the existing ones when adding new details or changes done during implementation or subsequent testing. This will allow you and other readers to see the evolution of the project and understand the why behind the decisions made.

Summary

Here are some helpful bullet points from what was discussed:

  • Write a one pager of the problem and solution requirements before writing the design doc.
  • Before writing the document figure out your stakeholders and teams/members impacted by the design
  • Make sure there will be no access permission issues to the document
  • Make it available to the widest audience possible
  • Don’t hesitate to mention the document in meetings
  • Directly ping/tag your direct stakeholders if needed
  • Book a meeting to present an outline of the document to your team
  • Set a deadline for feedback
  • Have a meeting to write the consensus of the document if needed.
  • Have a weekly meeting to discuss ongoing design docs and their state.
  • Update the document with the consensus reached
  • Keep the document up to date with the latest changes and dated sections to reflect the evolution of the project.

Timeline

Let’s try and integrate the above advice into an extract timeline of your Software Development Life Cycle (SDLC).

SDLC

Conclusion

The following might not apply to every team or organization or even every project. The important thing is to find what works for you and your team and examine what happens before and after the document is written instead of trying to only optimize design document writing.

Most of the time, the problem is not the design document but the process around it.

If you have any questions or comments, feel free to reach out to me through my email (in my homepage).

  1. https://en.wikipedia.org/wiki/Software_design_description ↩︎

  2. https://en.wikipedia.org/wiki/Product_requirements_document ↩︎

  3. https://en.wikipedia.org/wiki/Software_requirements_specification ↩︎