A Designer Who Writes Docs
For the first few years of my career as a designer, I didn't recognize writing documentation as part of my job.
In our fast-paced industry, the scope of a designer's role has gradually expanded, and communicating purely through graphics is no longer enough.
Designers are now handling a much broader range of communication, and writing documents has become just as crucial as creating images.
Especially at a startup like the Alarmy team—where every teammate is empowered to freely define problems and drive solutions—writing solid documentation plays a massive role.
You have to build consensus so everyone recognizes the problem you've discovered, and you need to communicate your solution clearly and comprehensively. That's why document writing is one of the most critical communication skills you can have.
Because I was a designer far more used to images than text, I used to feel an immense amount of pressure about writing docs. But eventually, I realized that writing and designing are actually incredibly similar—they just use different methods of expression.
To help anyone else who might be struggling with documentation like I did, I’d like to share how we write docs here on the Alarmy team.
Put the What, Why, and How Right at the Top!
What: What you want to do
Why: Why you want to do it and what problem you've discovered
How: How you plan to solve it
If you align on just these three things up front, it becomes much easier for readers to anticipate what the document will cover.
There is a massive difference in comprehension between reading a document with a rough idea of its core message versus going in blind.
By the very nature of work documents, if readers can't immediately grasp what it's about, they end up wasting a lot of energy just trying to understand the context, and there's a risk of teammates walking away with completely different interpretations of the ultimate goal. To make it easy for anyone to understand, try writing the core What, Why, and How as clearly as possible right at the beginning of your document.
(When defining the problem, including the background and history helps tremendously in establishing the context of the document.)
Leverage Your Strengths as a Designer (Clearly Communicate with As-Is and To-Be)
Once the core problem and solution are defined, the document will naturally dive into the specific implementation details of that solution.
No matter how accurate or detailed your written explanation of the implementation is, it rarely beats the effectiveness of a single visual element.
Sometimes one easy-to-understand visual communicates the point far better than a hundred words. Since designers excel at visual expression, you should actively leverage that skill when writing documents.
You can map out the user flow in a visual chart to convey the implementation scenario at a glance, or you can effectively illustrate your final goal by comparing "As-Is" and "To-Be" images of the elements being modified or created.
Share Docs Early and Evolve Them Together
Writing a perfect document on the first try is hard. It's especially difficult to map out the final, fully-realized solution entirely on your own.
Just like design, sharing your document with teammates early on and iterating based on their feedback will ultimately save you time.
As with design drafts, sharing an unfinished piece of work might feel awkward at first, but to align on the right direction and refine the document through diverse perspectives, I believe sharing it before it's final is crucial.
Brainstorm with your teammates about whether your document is heading in the right direction, if there's a better approach, or how to overcome areas where you're stuck.
You'll be able to manage your document much more efficiently—and find better solutions—if you explicitly list out the discussion points where you need your teammates' input.