Write Your Own Manual

SmallComputerHandbook

You can become a better software developer by improving your ability to organize information. A key part of that skill is being able to communicate what you know in writing. Whether you’re enlightening your peers on Stack Overflow or writing FAQs for your team, it’s good to have a reputation as a person who Knows The Answers. If you can write clear technical designs, how-to guides, and other documentation, you can have a lot of influence. In fact, even if you just write for yourself, you can get things done faster by avoiding trips to the Web to repeatedly look up the same information.

Here are some tips on when, what, and how to write as a programmer.

Write Before You Build

A number of years ago, I was responsible for hiring a developer to temporarily join my team and work on deployment automation. Since the schedule was tight and the code was “just” going to be used for deployment, I had him jump right in and start coding, asking questions about the system as necessary.

In retrospect, it would have been better to spend time up front updating the manual deployment steps. For a deployment feature in particular, manual steps coexist well with automation. Every bit of automation helps, but if you don’t get all of the automation written, you can still run it in combination with manual steps.

More generally, a written technical design gives you a chance to ask people to think through a feature. They may not be able to execute each step, as they can with manual deployment documentation. But a document can prompt knowledgeable stakeholders to point out deficiencies in your design.

Design documentation has gotten a well-deserved reputation as a pointless exercise to produce a long, boring document that no one reads. But a short document covering a limited scope and focusing on key aspects of a feature can go a long way towards making sure you’re building the right thing.

Even when there’s already something written, it can help to do your own writing. In my process for solving programming puzzles, I include a step for writing your own version of the problem statement. I find that writing down the key points in my own words helps me clarify what the problem is asking for.

Write Before and After Talking to an Expert

Here are two pitfalls of asking an expert for programming advice:

  • Pitfall #1: You know so little about the topic of your question that you don’t understand the answer you get, or you get the right answer to the wrong question.
  • Pitfall #2: You ask the right question and get the right answer, but you later forget it and have to bug your expert again.

Pitfall #1 can be solved by writing before you talk to your expert. Write down everything you know about your question, and everything you can learn about it from search results. That helps you focus your question so that when you ask your expert, you’ll be asking precisely what you need to know, and you can focus your question on what no one has yet documented.

Then when you get your answer, write it down in as much detail as you remember. Do some more research if necessary now that you have additional context. If possible, write it somewhere that others can get to. By contributing to your team’s documentation store, you’ll help future developers with the same question, and give the expert a chance to get more of his or her own work done.

Write For Yourself

It’s best to write your documentation where other people can read it, like on Stack Overflow, a wiki, or a shared OneNote. That allows others to contribute, and maybe even improve what you started. But it can also be useful to write documentation just for yourself.

In Learning How to Learn Competitive Programming, I mentioned a technique attributed to Charles Darwin, or maybe Richard Feynman. On Reddit, it’s called Explain Like I’m Five (ELI5). The idea is to explain a concept in the simplest terms you can, to make sure you really understand it. Writing documentation for yourself is a way to accomplish this.

Writing for yourself also allows you to distill answers that you find on the Web. If you need an answer once, you’ll probably need it again. Rather than searching for it every time, write your own version of the answer in the form that’s most useful for you.

Write Code Snippets

In an API reference like the Java documentation, programmers appreciate examples. The same is true on Stack Overflow. While it’s necessary to combine the code examples with explanations, examples are what solidifies a concept in a programmer’s mind.

Like explaining a concept in your own words, writing your own code examples ensures that you understand a coding concept. When I’m working on programming puzzles, I update a reference class of useful snippets. When I’m first learning how to use a language feature, I’ll check the official docs or Stack Overflow. But subsequently, I can find the answer in my reference class, which is customized for programming puzzles.

Characteristics of Good Documentation

For programmers, documentation is not the product. The product is software, and the documentation is just there to support it. In this article, I’m not even talking about customer documentation that is produced by professional writers and published along with the software. When you’re writing your own manual, you’re supporting yourself and the programmers you work with. That type of documentation has to be written efficiently, so you have time to get back to your real job of writing code. Here are some ways to check that it is:

It covers the right topics

Write documentation just in time, in response to actual needs. If you’re in an early design phase and getting feedback, write a short document first. Once you hear from people, you’ll know which parts of the document need to be expanded. They’re the ones that people have the most questions about.

It focuses on examples and other practical information

One of the reasons Stack Overflow is so useful is that its content is based on actual problems that people have encountered. With a traditional design document, there’s always a danger of writing for the sake of writing, because someone asked you to. Using real examples is a way to avoid that.

It’s easy to update

If you or your colleague needs to change something in your documentation, or want to document something new, the process needs to be easy. If there’s too much friction, you may not make the effort to do it. The gold standard for low friction is internal OneNote documentation: everyone is a trusted user, and they can just start typing in the document. But even public sites Stack Overflow and Wikipedia endeavor to reduce barriers to adding content, because people on the Internet are easily distracted.

It’s written by the people who know the most about a topic

Writing production code is an activity that only developers can do. But writing technical documentation is most efficient when the people doing it have an intimate knowledge of the system being documented. It’s hard for someone who is one step removed from the code (i.e., a professional writer) to learn all of the details. So developers need to spend some time writing about their work.

Write Your Own Manual

Wouldn’t it be great if, on your first day at a new job, someone handed you a manual that told exactly what to do in any situation? Actually, that sounds terrible. Fortunately, it’s more likely to happen at a fast food job than a programming job.

But what if you could write your own version of that manual? Over time, you could document everything you know and learn with a clear answer, freeing your mind up to work on new problems. Try it and see what happens.

(Image credit: Eric Fischer)