Are You Documenting Your Project Enough?

Writing documentation is important but tedious. We’re all probably aware that we have to write documentation for the products we develop. I don’t know how you feel about it, but when I do it, it hurts my brain.

It’s not even that difficult (most of the time), but the whole process around it is what makes it so dull. Personally, I enjoy writing, but even I have to force myself to write a couple of sentences about what I’ve done. But you gotta do it, baby.

I’ll be explaining the techniques we incorporated in our workflow to improve the whole documentation situation. If you’re struggling with this, I’m sure you’ll be able to take away some ideas from this post.

I won’t spend too much time explaining why documentation is important and who benefits from it because I’m sure you already know that. I’ll mention some problems that I’ve run into when dealing with documentation.

When I first started working at Productive, there was already a fair share of documentation. A lot of things were documented, from setting up your workstation to details about using a specific component. I was excited about being brought up to speed with everything, but I started running into cases and features that were either not detailed enough or not documented at all. Even though I was optimistic at first, this didn’t really surprise me since it’s a huge codebase with a lot in it. This just meant that I’d have to ping other colleagues and figure some stuff out on my own.

Fast forward a couple of months, it was my time to write documentation. Up until this point, I was very excited about documenting everything I’ve done. But when it was time to write something, I had this nagging feeling in my head. I knew that it had to be done, but now I had to think about how and why something was done in a particular way, how detailed the explanations should be, where to actually write the documentation, and a whole lot more. It’s even worse when it’s a system that you don’t completely understand and you start asking yourself if you’re the best choice for writing this piece of documentation.

So many problems—and I haven’t even started writing any documentation yet.

Now, this sounds a bit more dramatic, but all of these thoughts passed through my mind at some point. We quickly brainstormed a couple of ideas to tackle the problems mentioned above. If we had some sort of a process and a frictionless way of writing documentation, everyone would have a lot more brain power to actually write documentation as opposed to worrying about issues related to writing documentation.

Here are the things we agreed upon:

Now, let me take you through each.

This is something I had to get used to, as you can probably tell from my experience when I just joined Productive. It doesn’t mean that you should only document new features you’ve worked on, but even the old ones that you might not completely understand. You can always request a review from someone who has more experience to double check what you wrote. Even if it isn’t entirely correct, it’ll probably be much easier for the other person to advise what to focus on as opposed to a blank slate. An important thing to mention is that we also encourage asking more experienced colleagues to write a part of the documentation if it’s something complex or too difficult to piece together.

This ties in nicely with my previous point. Since documentation is something you iterate over constantly, it’s okay to just write some information down without paying too much attention to grammar, structure and completeness. It’s important to create a process that is as frictionless as possible in order to increase the engagement of everyone in the team. You can always improve the wording a bit later and other people can give feedback really quickly, even if they don’t fully understand the feature you’re working on.

Besides documenting new features and maintaining old ones, make sure that incomplete documentation gets the love it deserves. More often than not we run into something that exists in the documentation, but our specific case isn’t covered. This could also mean we’re approaching an issue in the wrong way, but still, we have to take initiative and document it. Chances are that someone else will have the same issue and if you take time to document it, they will have to spend significantly less time handling the issue.

Documenting something this way could be considered a “bottom-up” approach. Instead of documenting the whole process/feature, you just write down the specific case. Doing it this way could be a little bit “easier” because you don’t have to know every little detail about the whole feature. Just remember, whether it’s an onboarding topic or something highly technical, it should be a candidate for documentation to avoid confusion!

This one is, subjectively, the hardest. The whole process is simple: just like with continuous integration and continuous deployment, we have to maintain our documentation at all times. If a process/feature is worthy of documentation, a good time to write something about it is just after the process/feature is stable. A better time to write something about it would be even before you start coding, if that’s possible for the feature you’re writing about. Writing down everything while the information is still fresh will help you flesh out the whole story, not just parts of it. If you’re writing about it a couple of weeks later, you’re bound to forget some of the nuances that bugged you during development. Doing it later on could possibly be the beginning of incomplete documentation, so it makes sense to nip it in the bud.

Having outdated documentation is worse than having no documentation. This will just raise questions when something doesn’t behave as it says in the documentation. If you find yourself in a similar situation, make sure you delete it so it doesn’t confuse more people.

As mentioned, another approach we’ve considered is writing documentation before you start coding. This is something we’ve found helpful, gathering your thoughts around a feature makes developing it easier. This is also a great way to include non-technical people in the process and iron out some discrepancies even before a line of code has been written.

Having documentation is really important for everyone, no matter the seniority level or the amount of time you’ve been working on a project. Having said that, it’s not easy to encourage yourself or others to just write documentation.

You can make this a lot easier by reducing the amount of friction when writing documentation. Start by defining a time and place for writing documentation and involving your whole team. 

While you’re researching tools that could be helpful, don’t forget to check out Productive and our Docs! It could be helpful to add the extra step in your workflow, like including it in the estimates and requiring changes in the documentation when submitting a pull request. You can treat this just as you would treat writing tests since they complement each other. This will, most certainly, increase the time required to finish a task, but it’s just as important as the other parts of a feature.

This should make a good foundation for everyone to contribute and iterate over each other’s work. Hopefully, these small steps snowball into a more manageable project and make everyone’s life easier.