Collaborative Web Development

Chapter 4. Documentation

Writing is hard work. A clear sentence is no accident.

William Zinsser, author of On Writing Well

I’m going to begin this chapter by describing two common scenarios in the life of a developer.

In our first scenario, meet Harlow. Today is Harlow’s first day on a new project. The team has a well-established codebase, a great working environment, and a robust test suite. As Harlow sits down at her desk, she’s excited to get up to speed with the team. After the morning stand-up meeting she’s pointed to the project’s documentation for installation with a slight grimace from her colleague Riley. He mentions that the docs “might be a little out of date, but should hopefully be enough to get you going.” Harlow then spends the rest of the day following the documentation until she gets stuck at which point she is forced to dig through code or ask colleagues for guidance. What might have taken a few minutes becomes a day-long exercise in frustration, tampering Harlow’s initial excitement.

In our second scenario, meet Harrison. He’s working on a web app and finds a library that, at first glance, seems incredibly useful for his project. As he attempts to integrate it with his codebase he discovers that parts of the API seem to be glossed over in the documentation or even undocumented. In the end, he walks away from the project in favor of another solution.

Though these scenarios may be slightly exaggerated, but I’m reasonably certain that many of us can relate. These ...