by Catherine Kleimeier
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.
Code without version control?
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.
We hope to help you fill in the blanks regarding documentation!
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.
Clearfire loves code comments!
Clearfire also loves readmes!
Here's a screenshot of our example Planning Document in Notion.
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.
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.
How Project Management software might look if we try to stuff all our developer planning in there.
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.
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.
Jotting down my thoughts in the process of problem solving has been invaluable, even if that means disrupting the process of testing out those thoughts.
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.
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.
A far less efficient way to share your thoughts.
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.
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:
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:
The "Current Status" and "Questions" section of our example Planning Document.
The "Planning" section of our example Planning Document.
The "Notes" or "Scratch Sheet" section of one of Clearfire's real Planning Documents.
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:
As you’re working:
When you finish a thing, or the data becomes irrelevant:
You'll be doing a lot of writing! Well, typing.
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.
Updating your documentation as you go is key!
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.
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.
By the time the project has finished, your Planning Documentation should probably be finished. Feel free to take it down from the wall, so to speak!
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!
Documentation is a crucial part of successful project communication – and even more so when you have a remote team. We know that it’s impossible to deliver a complex project successfully without documenting it from inception through post-launch.
Search Console is a tool from Google that can help anyone with a website better understand how they are performing on Google Search, and what they can do to improve their appearance in search results in order to bring more relevant traffic to their websites.