What should a design doc include?

Remember: Write for the human brain, not the compiler.

When you write code, you write for the compiler, which can understand that you start at the top and work your way to the bottom with full details. But the human brain functions differently. A human brain understands things better if you give it the story of the code. While writing for humans, start the story with the primary use case, then build up to the big picture, show them the workflow, then introduce the areas of impact. At this point, you may include high-level code implementation details. And end the story with the future scope for the feature. In summary:

Possible sections Description
Objective In case of a new feature, mention the overview of the feature in terms of requirements. In case of a bug fix, mention the Problem Statement.
Big Picture/Context View Describe how the feature fits in the existing architecture.
Background and prerequisites Describe the concepts and theory that the reader must know to understand the objective and the solution.
Possible solutions List and analyze the possible solutions that can be implemented to achieve our objective.
Solution Describe the chosen solution and give the rationale behind the choice.
Workflow Describe how the solution works.
Areas of impact List the components and modules that are affected by the chosen solution. Describe the impact and workarounds, if any.
Code implementation Give a high-level overview of the code implementation.
Scenarios not addressed Describe the scenarios or use cases that are not addressed by the solution.
Future work Describe the future scope for the feature, if applicable.

Process:

Design docs are usually written as an after-thought. This practice can make writing design docs seem like a mammoth task that you are forced to do. Instead of writing it at the end in one shot, you can write it in chunks by following the Feature Calendar:

Feature Calendar Milestone Section of design doc corresponding to the milestone
Team discussion meeting High-level requirements

Big picture view

Engineering requirements meeting Functional specifications

Possible solutions

Design decisions

Design review meeting Proposed design

Areas of impact

Workarounds: How are we going to handle the impact

Demo/KT Code implementation

Scenarios not addressed

Future work

 

Tips and tricks:

The design doc is not the English translation for the code, it complements the code

The design doc should include all the information that cannot be understood from browsing the code, and no more. It should be a preface to the code.

Write in a conversational tone

While writing design docs, we tend to use formal language and technical jargon. Instead, use a conversational tone and write as if you are explaining the design to someone in person. It would make the reader’s life much easier.

Know your audience

Choose the sections to be included in the design doc depending on your audience. For instance, if the QA team is the audience, you might want to add a section on what are the at-risk aspects of the design, so they can focus on testing it. Or if the UI team is the intended audience, you can elaborate on the requirements from the UI perspective.

For developers: Why write design docs?

“Code does not tell the whole story”

Imagine that you have joined a project that is halfway done. You download the code and decide to browse through it. Where do you start? If you don’t have someone to walk you through the code, you start to make your own assumptions based on the limited knowledge you have about the project. Further analysis of the code will prove or disprove your assumptions, but will also give rise to another set of questions.

You would probably understand what the code does, but have no way to figure out why did the developer write it that way. What were the logic and the design decisions? What were the requirements and the constraints? Were some other modules impacted?

If you put in a lot of efforts and bug your fellow developers to help understand the code, you may be able to answer some of these questions. But it would take a lot of time! And you face these issues even when you have been a part of the organization for quite some time. Imagine what a new hire would have to go through.

There’s another layer of information sitting above the code that explains all this. This information should be captured in supplementary documentation – the design documents.

Designing a good piece of software is not enough. It has to be communicated in a way that lets its stakeholders use it properly to do their jobs. A good design document speaks for you. It speaks today when you should be doing your core job of creating awesome software, instead of repeatedly answering a hundred questions about the design. And it speaks for you tomorrow, when you have moved on to another project and someone else is responsible for that software.

In summary, design docs help you to:

  1. Educate:

Design docs serve as a medium to introduce the software to new hires or people new to your team.

  1. Record:

Design docs help you capture the information and design decisions for reference.

  1. Communicate:

Design docs help you communicate your design, analysis, and decisions to the stakeholders. Depending on how well the document is written and what vantage points it considers, the stakeholders can be Project Management team, fellow Developers, QA team, Technical Writing team, and Sales and Support teams.

Conference Report: STC Pune Regional Conference 2014

Society of Technical Communicators (STC) had organized a Regional Conference in Pune on Saturday, 28th June, 2014. I presented at the conference and thought of sharing some insights:

1. Keynote: Other side of the coin:
The Keynote Speaker was Mr. Ajit Bhat, a Software Developer with 15 years of experience. He talked about how technical writers can make developers’ life easier:
– Take up the writing tasks that they need to perform and are not comfortable with, like proposal writing and design docs. And prepare docs that enable knowledge sharing across teams.
– Train them in writing well and improve their communication and soft skills.
– Get a handle on the technology that we work on so that the developers don’t have to spend time in bringing us up-to-speed with what is being implemented in the sprint. Basically, be technically sound and do your homework.
– Incorporate the docs and knowledge base that the Support folks prepare in the user docs.

2. The Fox and the crane:
This was a session about designing user experience through our documents. The Speaker basically talked about making the transition from being a technical writer to contributing to the User Experience efforts in our organizations. He also talked about how we can implement the UX principles in our user docs (or even internal docs) to ensure an effortless User Experience for our readers.

3. Documenting solutions:
In this session, the Speaker talked about documenting end-to-end solutions instead of feature-based documentation. I wish he had talked about exactly what to document and how, but the session gave me a lot of thinking points.

4. My session: Developer docs
My session was about making the transition from user docs to dev docs, the need and scope, the types of dev docs, and the process. The response totally exceeded my expectations and session turned out to be very interactive. It was fun!

Here’s the slide deck for my presentation:

Any feedback and review comments are most welcome :)

 

Why I am here, what’s this about

Hey there! I am Amruta Ranade, a Technical Communicator in Pune, India. In a past life, I was an Electronics and Telecommunications engineer.. but soon found out that I love explaining technology more than creating it. So what better job than being a Technical Communicator for Developer Docs! Now I create concept docs, software architecture docs, design docs, technical whitepapers, implementation docs at an amazing startup in Pune..life just can’t get better :D

This is my place in the online world where I share what I learn on-the-job. Join me for the ride :)