A Developer’s Guide to Planning Documentation

If you’re a developer, the chances are high that you reference documentation pretty regularly for third-party technologies and applications. Chances are also high that you don’t write much documentation of your own, considering how it’s often viewed as less important than coding. Here at Clearfire, however, we put a lot of importance on documentation and we have some insight into how to write your own. We find that it helps keep us organized, focused, and timely. It allows us to conceptualize complex projects and change direction without losing our way. In short, our documentation helps us to be our most effective. In case you still need a little more convincing about the value of documentation, though, please consider the following:

As a developer, you’re very likely experienced with version control and you probably place a lot of value in it. With version control, you have a centralized location for project work that’s accessible to everyone on the team, so that everyone can have the same context and understanding of the work. You create that context by tracking changes to the work over time and sharing it in a transparent manner. This allows for analysis, feedback, and planning. Perhaps most importantly, you’re making intentional and structured changes to your work through commits, rather than aimlessly coding and uploading files with no sense of what’s gone before or what may be to come.

Documentation is a lot like that. In documentation, you’re making your personal thoughts, processes, plans, and knowledge more accessible to others, so that everyone can have the same context and understanding. Depending on the tool or execution, you can create a shared context by tracking changes over time; those changes are available to everyone, in a transparent manner. You organize and structure your thoughts and plans in order to write them out and share them with others. With structured, contextualized, and shared plans, you’re adding intentionality and predictability to your entire process.

Organization, context, problem-solving, planning, and sharing are core principals of both version control and documentation. If you, as developer, can see the value in version control, then you can hopefully see that a similar value exists in well-written documentation. As a developer, however, it’s likely that you’re less experienced in writing and managing good documentation than you are in working with version control. This article aims to provide some guidance as to what good documentation is, why good documentation is important, and how to write and manage documentation. By the end, we intend to have given you everything you need to make your well-informed start into documentation.

What

First, what are we talking about when we talk about documentation? There are many different kinds of documentation, each with their own niche. At Clearfire, we tend to break these down into Code Documentation, Project/Feature Documentation, and Planning Documentation.

In this article, we’ll be looking specifically at the last type, Planning Documentation. It’s worth knowing and understanding the other types, though, so that we know what we’re not doing when we’re working on Planning Documentation. That helps us keep our scope limited and our work focused.

Code Documentation

• Lives in the code itself, usually in the form of comments, in the relevant context
• Explains what a specific, discrete piece of code (or other part of an application) does and why
• The purpose is to create a clear and informative record of functionality so that another dev, or the same dev at some point in the future, can understand that functionality easily
  • The comments shouldn’t be too detailed (no one reads things that are too long, no matter how much I, personally, may wish otherwise), but should aim to give enough context and instruction that any potentially unclear or confusing aspects are revealed and explained
  • Comments should be formatted in a way that aids that ease of reading and understanding… just like the code itself

Project or Feature Documentation

• Lives outside the code (usually) or in a README
• Explains wide, overarching aspects of a Project or Feature
• Can encompass technical details, like highlighting important methods, as well as more generalized aspects of the Project or Feature
  • A common purpose is to explain how a Feature works and why it works that way.
  • Another common purpose is to track and highlight aspects of the Project that are important, but not made obvious within the code itself. This may include places or methods for logging in, for troubleshooting common problems, for explaining some third-party activity like an API call or CRON job, for giving details about how a field within the CMS looks or behaves, and so on
  • Another common use of Feature Documentation is defining and outlining a Project’s build process. Those instructions and details can sometimes be too long or detailed to fit easily into a README, or they may require sensitive details, like account information, that don’t belong in a repo.
• May be written for the client or the developers, with the content tailored for that purpose
• We at Clearfire also find a lot of value in this kind of documentation, particularly for long-term projects, but that’s outside the scope of this article. Maybe we’ll write another to break this down, at some point?

Planning Documentation

• Lives outside the code (usually) or in a README
• The purpose is to create a clear and easily followed plan for working on a Project or Feature
  • This is separate from Task or Project Management in that it’s far more detailed, as the intention is to be specific about the work itself, while Task or Project Management is meant to create a general roadmap and timeline
    • If the PM software serves as the map for the road trip, the Planning Documentation serves as the detailed itinerary
• This should probably not be client-facing, as it’s mainly used (and created) by the developers to track their own plans, thoughts, and processes
• Common contents include
  • More detailed restatements of PM timelines, goals, and tasks
  • A breakdown of a particular goal and possible methods to achieve it
  • An order of operations for a particular task or a series of tasks
  • A detailed question-and-answer testing list
• The most important functions of Planning Documentation are organization, context, problem-solving, planning, and sharing.

Why

As mentioned previously, good Planning Documentation can be valuable for many of the same reasons that make version control so important. “But,” you might ask, “isn’t planning the whole purpose of Project Management software, like Basecamp or Jira?” I would answer that PM software is a vital part of the Project Management process, but that Planning Documentation is also important for developers. It’s a great place for real-time and synchronous communication that’s hard to achieve in PM software, and it’s a better place for the high-level plans and information than PM software. It’s great for organization, context, problem-solving, planning, and sharing.

Organization

It can be really difficult to keep track of all of the various aspects of a project in your Project Management software, particularly in the Planning phases. Your PM software might be great for assigning tasks and establishing timelines, but it’s hard to get a top-level overview of how the tasks fit together if they’re broken out. It’s also difficult to store the more “living” components of your plans in PM software, like requirements or strategies that are still being finalized or problems that you’re brainstorming. Planning Documentation is a great place for all the information.

Context

Planning documentation is a great place to put more generalized content that can be hard or inappropriate to put into code and keep organized, but that serves to help a dev (or anyone else) understand the what, how, why, and sometimes where of the work. Context is also history: if you’re using a tool that can track history, you can view trends in your documentation through time, which helps to give more context. Why is this piece of code here when it’s not in use? Well, it was 2 years ago and did this, but the client said they might turn that back on at any moment, so it has to be present to handle unexpected implementation. If that’s not tracked in your Planning Documentation, it’s easy for that information to be lost to time.

Problem Solving

Writing down your problem-solving process in context, and especially where others can see it, can provide a deeper understanding of the problem and give you more opportunities to get different ideas or points of view. If you’re not writing down your problem-solving processes or thoughts, it’s very hard to keep track of what you’ve already tried, what you intend to try next, and what the results or each attempt were. If you don’t keep track of those things, you run a high chance of repeating work, skipping steps, missing possible options or opportunities, not getting feedback from someone who may have insight, or just plain getting lost.

Planning

For planning larger or more complex work, most PM software just doesn’t cut it and isn’t the right place for detailed plans. Having dedicated planning documentation provides a place for extremely detailed plans and processes.

Sharing

By making your Planning Documentation the central location for the above information, everyone can know exactly where to look for most information. Everyone can easily get on the same page about plans. Everyone can chip in with a full understanding when someone’s brainstorming or stuck on a problem. Depending on the tool, they may also be great collaborative spaces for planning out multiple people’s work and responsibilities. Personally, I enjoy having the Planning Documentation open and reviewing it on a Slack huddle with other team members; the “whiteboard” effect it provides is incredibly helpful for a distributed, remote team. As Clearfire is such a team, we’ve found this to be a particularly helpful strategy for keeping all our people on the same page.

How

Now that we know what Planning Documentation is and why it’s so important to have it, we’ll go over how to create it, how to maintain it, and how to use it for later reference. There’s also a video demo in the next section, if you grow weary of reading my verbosity.

Creating

When you’re creating your Planning Documentation, you first need to decide what, specifically, you need out of this document. Since it’s a place to plan and track work, first figure out:

• What work are you breaking down in this document?
• What are the parts of that work that need to be broken down in this document?
• How would you structure those parts and that breakdown to make it easiest for you to understand and manage?
• Who needs to be included in this document?

One you have those questions answered, you can start the process of breaking down the exact work into manageable chunks, organizing them, and, perhaps, assigning them to the relevant people.

Here’s an example of a Planning Document that really highlights the “structure” and “breakdown” points from the list above.

That example illustrates some common components of Planning Documentation structure. Those components include:

• Table of Contents: So you can see the structure of the document at a glance.
• Current Status: So you can see and update the status of the project within the document itself
• List of Questions: Easy place to collaboratively ask and answer questions that may not fit into your PM software. At Clearfire, we put a lot of emphasis on clearly communicating expectations and answers, and having a dedicated place in the document to write those out is always helpful for us.

• Important Info and Documents: Necessary for easily finding relevant info or navigating to off-site places
• Planning: Where you break down the larger Project into smaller steps. The point for this section is to have a list of actionable items that are detailed enough to give you all the information you need to accomplish that action, without having so much information that finding, reading, and understanding it is an actionable item in itself. To generate the items and their accompanying information, you may want to start by listing out and recapping all the tasks, goals, timelines, etc from your PM software and then figure out where you need further info or documentation in order to know what to do and how to do it. Those places where you need further info are “gaps” to be filled with tasks, notes, and planning. Those gaps are really the purpose of these documents; it’s easy enough to check off straightforward to-do lists in PM software, but once you wonder how you can accomplish a task in that list, you should have a centralized place to plan it.
  • Features, Functions, or Goals: Breaking down the larger Project into groups of tasks, organized by their context or purpose, helps to create a clearer understanding of the structure of the Project and the status of the work.
    • Tasks, sometimes in order, with Assignees:
      • What needs to be done?
      • Any unusual notes on requirements or suggestions for how to do it
      • Who needs to do it?
      • When does it need to be done, either in terms of deadlines or in terms of order?
      • Note: The person responsible can then further break down “how to do it” here in a way that is helpful for them
        • Common patterns include jotting down thoughts or plans, making checklists, tagging others in questions, creating tables for comparison or steps, adding important notes for later reference

• Testing: Not completely necessary, especially if you have other software for testing, but I’ve found it helpful to track expectations in the same place as where the work to meet those expectations was defined. That helps to track down any issues a bit more easily than if the tests were tracked separately.
  • Feature → Function → Expectation / Action / Result
• Launch: Again, not strictly necessary. However, in my experience, it’s often helpful to have such disposable and mutable items as launch checklists in a software like Notion, where it’s so easy to collaborate and alter the documentation. Plus, I prefer to have more context for launch tasks in case something unexpected happens.
  • Tasks, in order, with Assignees
• Notes Section / Scratch Sheet: Probably the second most important part, in my opinion, behind the Planning section. Having a “disposable” area to write your thoughts down, especially when you can easily see other relevant info, and then copy/paste your solution into the relevant place, makes my whole workflow easier. From a personal perspective, almost every problem-solving process or big-picture planning session I do begins as a messy bullet list in the bottom of a useful document. I also enjoy the feeling of accomplishment that deleting a huge chunk of “completed” notes brings.

Maintaining

In another parallel with version control, it’s important to maintain your Planning Documentation. I also find this to be the most difficult part. It’s so easy to forget to cross off a checklist item, or a series of them, when I’ve finally finished a task. It’s even harder to remember to update a particular section of notes when I learn new information that’s relevant to a specific task.

The process of maintaining the documentation is simple enough:

When you’re starting to work on something, quickly review the documentation:

• Are there any new Questions you can answer, or Answers to your Questions? These might tell you where to start.
• Otherwise, look in the documentation for any Feature in the Planning section that relates to that work. If that feature has open tasks or notes on an in-progress task, start there. Make sure that the Status section is up-to-date!

As you’re working:

• If you run into a Question, add it to the Questions section.
• If you finish a task, check it off. Make sure that the Status section is up-to-date!
• If you run into something difficult or unexpected, take your problem-solving notes in the Scratch section. When you’ve solved enough that you have a plan, write that out in the Feature breakdown in the Planning section and erase (or move) your notes.
• 💡 A tip to make it easier to find what you’re looking for as you’re working is to put some (but not too much!) effort into formatting. Notion is nice because you can have multiple columns, which comes in handy for short lists or text blocks for subtasks under Features. Other software is perfectly acceptable, too, as long as it has basic formatting options. You can think about formatting your documentation like you format your code: add whitespace to visually separate less-related chunks, use indentation to indicate nesting and hierarchies, use text formatting options (like headings, highlights, and font styles) like you’d expect syntax highlighting to behave (tells you something without you even having to read it!) Note that color-coding can be a very useful formatting strategy, but keep in mind that color blindness is very common, so consider your team’s ability to effectively use the documentation you create. Perhaps emojis or text formatting are better options than colors for your team?
• 💡 A tip about collaboration is to keep cross-editing to a minimum. If someone adds something and you have something to say about it, make very clear that you are the one saying it, either with a prefix (Bob says: There’s an issue on Github about this here) or in a true “Comment,” if your software allows it. If you find that you’re leaving chains of responses that are longer than a single reply each, move it to a task in your PM software or to a synchronous communication software (Slack, a video chat, your voice, etc).

When you finish a thing, or the data becomes irrelevant:

• Either when you finish a task/feature or at regular intervals (probably with the help of reminders), look through the whole document and determine what information is related to still-active work
• For all other information, determine if it would be appropriate to be moved to code comments, Project Documentation (I can’t recommend this enough), or your PM software. If not, delete it.

Those steps ultimately condense into: check the document for new or actionable updates, update the document as you go, and move or remove things as they become irrelevant. That sounds simple, but simple isn’t always easy. That’s particularly true when you’re learning to use Planning Documentation as part of your workflow, like you would with your version control GUI or terminal window, and when your Planning Documentation is detailed and comprehensive (read: long).

With that being the case, here are some tips for making it easier to remember to update your documentation.

• Keep the Planning Document open in a Pinned Tab in the browser window you’re using most for the project
• Make sure your Table of Contents is clear and easy to scan (I use emojis in section titles for this, so that I eventually learn the icons enough that I don’t need to read the titles)
• Link to your documentation in your PM software (and maybe in your communication software, like bookmarking a link to it in the relevant Slack channel)
• Set reminders related to your documentation. These can be in your PM software, in your calendar software, in Slack, or wherever you’re actually going to look at them.
• Build time into the initial project budget for documentation, just as you would for project management. Use that time specifically, intentionally, and regularly for documentation! If you treat documentation like you treat tickets or tasks, your documentation is more likely to get the attention it deserves. After all, you don’t skip tickets or tasks, so don’t skip your documentation! It’s also easier to track the time you spend on your documentation to see if you’re behind if you have a specific amount of time set aside for it.
  • This might be a bullet point aimed more at Project Managers, but it’s something you can bring up with them if you find yourself running out of time while trying stay organized.

Later Reference

If your Planning Documentation is well-done, it should be full of useful links and historical context. Perhaps most of that information was gradually migrated over to your Project Documentation as it got crossed off the “actionable” checklists, leaving it a mostly-empty shell of plans, links, and notes. That’s fine! If your documentation software (we use Notion, but Slite, Dropbox Paper, Evernote, and others are also great) allows for viewing updates, you still have a rich history of dates and changes that can be important to hold onto, if your PM software doesn’t allow for easy searching.

The drawback to having all that information is that it can be hard to find something you’re looking for, particularly if your documentation is extremely long, out-of-date, or disorganized. To that point, the best way to optimize later use of your Planning Documentation is to do the work now.

• Remove unneeded info.
• Check off completed work
• Re-organize as needed

If you’re using software like Notion, where searching is comprehensive and easy, this is less of headache.

In theory, because Planning Documentation is action-focused, an entire document should become obsolete when its goals have all been met. When you’re approaching the “review” phase of a project, consider checking your documentation to see if you can delete it completely; you don’t need the extra processing of having to look over a completed checklist document forever.

Recap

That’s it; you’ve reached the end. Congratulations! You should now have a better understanding of what Planning Documentation is (a central location for the high-level and expansive planning breakdown that isn’t easy to fit into PM software), why it’s valuable (context, context, context!), and how to create it (break it down, one step at a time). If you can approach your Planning Documentation the same way you approach building out a feature in code, you should have no problem creating organized, helpful, maintainable documentation that serves everyone on the team. Good luck!