“I’m a developer, not a writer.”
Maybe you’ve heard one of your peers say this before. Maybe you’ve even said it yourself! There are times when writing documentation will benefit everyone, but it can be intimidating if writing isn’t something you get excited about naturally.
In this post, I’ll share five tips that apply to any type of documentation, whether it’s an API reference, an overview doc for a technology or product, or a step-by-step walkthrough. (While this post focuses on internal documentation — that is, documentation that you create for users within your own company—the principles apply no matter who your readers are).
First: Developer, You Know More Than You Think!
The principles of writing good documentation aren’t that different from the principles of writing good code: they’re both forms of communication. So if you’re a developer and you need to write documentation, there’s nothing brand new that you need to learn. Instead, you can take what you already know about software development and apply it to documentation.
1. Give Context
Providing context enables readers to know right away if they should keep reading, or move on to something else.
Say you have a large code block that does some complex processing; it’s common to put a comment at the top to explain what it does, and why. And, heck, maybe even who wrote it. This gives anyone reading the code important context about it—facts that aren’t obvious from the code alone. (And, don’t forget, that person might even be you at a future time!)
You want to do the same thing for anything you write, not just complex code blocks. When it comes to documentation, context is king. As soon as users start reading, you want to orient them, by communicating:
- who wrote the documentation,
- when it was written,
- and why.
To give credit where it’s due, this sage advice comes from
Ian Varley, a Salesforce architect and regular contributor on our
@SalesforceEng blog. Here’s what he has to say about context.
Here’s an example: If I’m writing some documentation, I add a paragraph to the top with this information. Below is such a paragraph with some of the names changed:
This document was created by Dianne Siebold in Jul 2016 to describe the SuperCool REST API. This document is for anyone that wants to integrate with and access the SuperCool data using this API.
When I write a context paragraph, I imagine what information would be helpful for someone from a completely different part of the company with no knowledge of what I’m writing about.
2. Use Pictures
Whenever you can, use pictures and graphics in your documentation.
In the world of software development, complexity is a given. It’s common to work on a feature or system that uses processing or business rules that are just too complex to hold in your mind all at once. That’s why most specifications contain graphics of some kind. That could be something like a flowchart, showing the route of processing. Or it could be a UML diagram. When you have to pick up a pen and paper to explain a piece of code or software, it’s time to use a graphic in your docs.
Graphics can communicate some kinds of complex ideas more quickly than writing, and they’re a great “visual reprieve” from endless paragraphs of text. The right diagram can save readers lots of time understanding something, especially when it seems too convoluted to explain in words.
The diagram below is a perfect example. You could probably write thousands of words to describe the relationships between badge and reward objects in Work.com. But, imagine if you had to read through text to get the information that is quickly conveyed in the diagram!
3. Know Your Audience (and Write for Them)
Ideally, as a developer, you keep your customer in mind as you’re working on any new features or updates. You think about their goals, what they’re trying to accomplish with your software, and how they’ll be using it. Then you try to create a feature that’s functional, easy-to-use, and follows the chain of tasks that a user would follow to accomplish that goal. The same is true for documentation.
When you write documentation, think about what your readers need to do. Write to address their needs and the problems they may encounter. It sounds obvious, but that doesn’t mean it’s common; often we write documentation based on what we want to say about something, not on what the user needs to know. Doing that takes effort!
Let’s say you’re writing some doc for an API you wrote. You know you’ll have a reference topic that includes the resource name and URL, the parameters, an example request body, an example response body, etc. Reference documentation is great for users that are either trying to get a general idea of how the API works or for users that are already using the API and want to implement a specific call.
However, there might be users that are new to your API. So, it doesn’t hurt to start by saying things you think are obvious (like, why would anyone even use this API in the first place?). Then, you might consider choosing an example topic that walks the developer through calling your API through cURL or Postman from start to finish. It’s important to consider each level of knowledge. Alternatively, in the context paragraph, you can let your readers know whether you’re writing for a beginner or an advanced user.
4. Structure Your Doc
When you write documentation, doing a brain dump in a Google doc is a good first step. But don’t stop there. Now take all that information and structure it.
Think about it in terms of code: If you’ve got an idea for some new functionality, you might code it up just to get a proof-of-concept running and to get the idea out of your head. But you wouldn’t just take that big blob of code and put it into production, would you?
The next step is to think about how to structure the code so that it’s more efficient, maintainable, and readable for yourself and others. You might move code that creates a new record into its own function and the code that returns a list of results into a separate function.
The same is true with documentation. Content that’s logically and consistently structured, is easier to read and understand. This picture of the Apex Developer Guide TOC is an example of good structure. At the start of the documentation, there’s intro content and a “quick start” that gets you up and running immediately. Content that’s strictly for reference fits into a Reference category. If you have information about support and troubleshooting for your feature, it might make sense to create a separate category for that.
5. Use Consistent Formatting
When you write code, a consistent code style will help anyone that later works on your project. This includes consistent naming of variables, functions, and methods, consistent casing of all elements, consistent use of whitespace, indenting, and line breaks — you get the idea. It’s easy to overlook the value of these things until you work on code where these practices are ignored.
Consistently formatted code enables other readers to more easily understand it. Once you understand the “rules” that the developer uses in their code, it’s much easier to read and comprehend.
Formatting consistency is equally important in documentation. Consistent formatting implicitly communicates information about the structure of the document to the reader.
Good examples of consistency are the class topics from the Apex Developer Guide such as the one below. Each class topic uses the same format: headings for namespace, usage, and methods. The Methods section contains a bullet list of methods with brief descriptions followed by the methods themselves. The documentation for each method contains the description, signature, and return value.
These topics don’t just contain the information users need, but each topic is formatted exactly the same way. So it’s easy to scan and find what you’re looking for.
Takeaway
If you’re a developer, it’s inevitable that you’ll write documentation at some point. By approaching documentation with the same mindset as you do code, you can create solid, usable content without having to learn a bunch of new skills.
