Documenting Your Code

Documentation has a bad reputation. It is hard to find the motivation to write it, it's a nuisance to maintain, and our exposure to it over the years has convinced us that it is one of the driest and dullest methods of knowledge transfer. It doesn't have to be this way, though!

If we choose to focus entirely on the users, then our documentation can be simple and pleasant. To do this, we must first consider who the users of our documentation are. What do they want? Every user, whether a GUI end user or a fellow programmer, begins the journey of using our software with a task in mind. It's our duty, both within the software and through its documentation, to enable them to perform their task with as little pain and confusion as possible. With this in mind, in this chapter we'll explore what it might mean for us to construct such pain-free...

Aspects of clean documentation

The purpose of documentation is to communicate what a piece of software does and how to use it. We can split the characteristics of clean documentation into four aspects: a clean piece of documentation communicates the concept of the software, provides a specification of its behaviors, and contains instructions for how to perform specific actions. And it does all of this with a focus on usability. By the end of this section, we will hopefully understand the vital importance of the user in the craft of building clean documentation.

Documentation is something most people don't think about a lot. It's usually an afterthought. My task in this chapter is to convince you that it can be, and should be, so much more than this. As we step into these aspects, forget what you know about documentation – start with a fresh canvas and see if you...

Documentation is everywhere

If we generously define documentation as a way of learning about a piece of software, we can observe that there are dozens of different mediums of documentation that exist. Many of them are implicit or accidental; others are more intentionally crafted, either by the creator(s) of the software or the expert community that has gathered around it:

• Written documentation (API specifications, conceptual explanations)
• Explanatory images and diagrams (for example flowcharts)
• Written tutorials (walk-throughs, recipes, how to do X)
• Rich media introductions and tutorials (videos, podcasts, screencasts)
• Public Q&As or issues (for example GitHub issues that explain how to fix something)
• Community-driven Q&As (for example StackOverflow)
• Independent communication between programmers (online or offline)
• Meet-ups, conferences, and seminars (owner or community...

Writing for non-technical audiences

As we have seen, when writing documentation, there is a need to adapt the language used to the audience. To do this, we must have a good picture in our mind of who the audience is, what their current level of knowledge is, and what they're trying to accomplish. A notorious challenge for programmers is communicating with less technical or non-technical people. This is a very common and crucial part of their role as a creator of software. Whether communicating with end users at specific points in a UX, or collaborating with non-technical stakeholders, there is a need to tailor our communication to the audience. To do this, we should do the following:

• Pick the right level of abstraction: It's crucial to find a level of abstraction that is fully understood by the audience. Use their roles and proficiencies to inform the analogies you...

Summary

In this chapter, we have explored the difficult art of authoring clean documentation, breaking it down into the four vital aspects of clean documentation: concept, specification, instruction, and usability. We've discussed the challenge of correctly identifying our audience and how to craft our communications to suit them. This knowledge will not only be useful in crafting formal documentation, but also in our everyday communications with stakeholders and within our software when it needs to communicate with users.

In the next chapter, we move swiftly on to the unique challenge of dealing with other peoples' code. What happens when we, on the receiving end of potentially poor documentation or unintuitive code, need to be productive? We'll find out.