This chapter is from the book
This chapter is from the book
This chapter is from the book
Writing about Software
You’re probably familiar with the classic outline: a hierarchical, indented list of items. It’s a fantastic way to keep track of projects, and there are plenty of apps out there for keeping such lists. While reading this chapter, though, think about all the different practices there are for writing about software design and development:
- Traditional outlines are great for exploring ideas in your initial mental sweep, constructing requirements documents, and communicating complicated ideas to a team. At any point in a project, if you find yourself up against a complex problem, consider building a traditional outline to make sense of it. Folks with analytical minds often feel that outlines are the most natural way for them to organize information. You’ll find a number of excellent outlining applications for Mac and iPad that make it easy.
- Plain text files are a nice, simple way of jotting down ideas and things to consider. But it’s harder to make text files hierarchical and clearly itemized. They’re easy to share, especially if you keep them in sync via a cloud service.
- Tasks in a to-do application can keep you on track once you’ve figured out what needs to be done. They tend to be ephemeral and personal, though, rather than providing a team with a comprehensive and definitive record of everything about a topic.
- Tickets in a bug-tracking database make it easier for everyone on a team to see the current understanding of a problem, the discussions that have happened around it, and the proposed solution. But they’re not great at giving a big-picture view; you can’t rely on bug tracking to help you understand anything bigger than an individual problem.
- Paper and whiteboards are perfect for quick, in-person planning on your own or while meeting with someone else. And there is still no easier way to gracefully combine outlining and sketching. Once you’re finished with a whiteboard session, you can take a photo for safekeeping, in case you ever wonder, “What were we thinking in that meeting?”
- Plans in project-management software are a formal way of keeping track of what needs to be done. For project managers and other boss types, they can be invaluable for keeping an eye on the big picture, but they’re not very useful for focusing on the decision-to-decision detail of a tough design problem.
- A design specification, or “spec,” is a definitive, complete description of a team’s plans and intentions for a piece of software. Depending on how formal your organization and your processes are, you might even be required to follow the IEEE 1016 standard for this kind of document.
Most likely, you will find yourself using some combination of these tools to keep track of the various levels of detail in your design project: attaching text files to bug reports, transcribing photos of whiteboard lists into specification outlines, and so on. Which ones you prefer will depend on how much detail you need, whether you’re working with a team, and which apps you’re comfortable using.
What’s important is to put together comprehensive, itemized lists of things that need to be considered for your project, from the grandest goals to the tiniest, hair-splittingest details. Some outlines may be hundreds of items long, such as a write-up of all the components in the architecture of a complex app. Others may be just a handful of highly precise decisions that took hours of agonizing to get just right.
Even if you don’t prepare formal specs, it’s often invaluable to have a single document (or set of documents), as casual or as formal as you want, to fully describe the team’s understanding of what it is they’re building. (And it’s helpful even if you’re not working with a team!) Keep these specs checked in to your version control system just like source code, and keep them up-to-date.
Also keep the designs for—and the discussions about—rejected ideas, because they illustrate why you didn’t go with a certain seemingly appealing choice. Rejected ideas keep you from having the same arguments over and over again, and they become part of the “antirequirements” of the app, described later. Treating the software itself as its own spec is a great way to lose track of important work that needs doing, or for people to misunderstand incomplete bits of the software as being intentional and already finalized.