7 essential tips for writing technical documentation

Working in a company with a huge number of plans, where over 300 developers keep adding new features, it’s very hard to stay organized and keep track of everything — even in your part of the product. That’s why at Pipedrive we can’t imagine smooth development processes without effective technical documentation.

But here’s the catch: simply listing out the product requirements doesn’t cut it. You need to craft them in a way that’s crystal clear to everyone involved. Learning from our own trials and errors, we’ve come up with a set of rules that have revolutionized our workflow.

• We’ve managed to significantly cut down on those unexpected bugs that pop up during the testing round due to overlooked scenarios.
• Our team communication has become more streamlined, as the need for constant clarification has vanished.
• And, with clearer guidelines, our developers now spend more time doing what they do best: bringing features to life at increased speed.

By leveraging our experience, we’re excited to share some essential tips and techniques that will sharpen your technical documentation skills. Whether you’re a veteran or a newcomer, these insights are designed to transform your documentation into a masterpiece of clarity and usability.

Tip 1: Write with the precision of a lawmaker.

Effective documentation must be clear and accessible to everyone — from developers to your company’s CEO. Like well-crafted legislation, it should avoid ambiguity and double meanings, ensuring that its message is understood identically by all readers.

To illustrate the importance of writing with precision, consider the following anecdote, a perfect example of how clear communication can prevent misunderstandings:

Tip 2: Embrace specificity

Asking for specific outcomes in technical documentation is crucial. Consider the difference between telling a cab driver simply, “Drive me around” and giving them a specific address. The second ensures you reach the exact destination you intend. Similarly, vague instructions in technical documentation can lead to unexpected product results.

For precise and actionable guidance, describe technical requirements using the “when-if-then-else” pattern. This approach not only specifies conditions but also anticipates various scenarios, ensuring that none of the cases are forgotten or implemented incorrectly.

Remember, that any overlooked requirements can be approached with the artistic mindset of, “I just see it this way,”. like in this example:

Tip 3. Forget about the “Ancient Mysteries” approach

Avoid using phrases like “do as it worked before” or “screen X has the same logic as screen Y”. It won’t help future readers understand how the feature works. Moreover, it can bring more misunderstanding during the testing round.

Resist the temptation to take shortcuts. Dedicate an extra five minutes to detail the behavior of features. While it might seem that everyone currently understands (or believes they understand) the implementation details, time can blur these memories.

Tip 4. Visualize it!

A picture is worth a thousand words. Unleash your inner artist by creating diagrams so intuitive, even a penguin could understand them. When describing the user’s journey through your app, especially with its various paths and decisions, what could be better than a flow chart? Tools like Lucidchart or Draw.io are perfect for crafting them!

Tip 5. Treat your design as the source of truth

Ensure the integrity of your project by requesting that designers keep the Figma (or any other design tool) workspace organized. This includes removing any draft versions and promptly updating designs to reflect changes in requirements during development. Maintaining a clean and up-to-date design space is crucial, as it acts as the authoritative reference for development.

Tip 6. Pretend you know nothing about the code.

Avoid fixating on the particulars of platform implementation. If you’re an iOS developer, it’s obvious that you’ll explain the behavior based on the known code implementation. However, keep in mind that the approach might be entirely distinct on Android, for example.

Articulate concepts as though you have never seen the code. Use business terms, not development ones.

Tip 7. Prepare for the best, plan for the worst

The devil is in the details, and the user’s experience lies in how well we handle unexpected cases. Make it a priority to thoroughly document how your application should respond to less-than-ideal situations. For example, if there’s a “Save” button, specify the system’s reaction to a failed save attempt. For network requests, elaborate on both successful outcomes and error states.

By following the advice from Tip 2, you’ll naturally include plans for when things don’t go as expected. Remember, whenever you write an “if” statement for what should happen, add an “else” statement right away. This helps prevent you from forgetting to explain what should happen if things don’t work out.