How to document code - getting started

Software development can be challenging. Do you know what else is? Writing.

People give up on writing documentation for a project because it is hard. Some may believe that it takes away time from the software development process. But documenting is software development too!

Good documentation can help you establish authority in what you do well. Having all the documentation inside your head alone is an admirable skill but is limiting. It is tricky to use a project where there are parts no one, except you, could understand. It benefits teams who could potentially use your project to build something useful, leading to the growth of your project in turn.

Let's dive into some ways in which you can overcome your documentation writer's block

Problem 1: I am not a writer

Of course, you are not. (Or maybe you are. But just not when it comes to software documentation.) Documentation isn't meant to impress, like ad copy. Humans are wired to communicate. If you can put reminders or ideas into a note app, you are capable of writing documentation. If you keep on writing for long enough, you are a writer!

Problem 2: I do not have the right tool for it

You do. Start writing notes in whichever note-taking app you already use. Keep it open by the side of your working window.

Problem 3: My documentation sounds stupid.

There are no stupid notes. Even docs that use incorrect grammar are better than having no documentation. You are doing great. It will get better.

You may be trying to explain something that you know very well, so it sounds silly to you. But it may not be that simple for someone who hasn't worked on your technology stack or domain.

I have certainly taken my knowledge of languages that I have used for years for granted. Maybe your reader doesn't know about that technology, API or tool. Here is a chance for you to share your expertise by explaining something they might need to learn. If you are writing simple docs that even a newbie can understand, then you must be doing something right.

Problem 4: I have very little to write about

It is possible that what you are working on is very simple (to you), and there isn't much to talk about, except there may be details you have missed.

It is time to bring out your inner 4-year-old, who asks several annoying questions. Poke at your project or team up with someone else and poke at it together. Find out from your users (if you have them.) Let them find sections in the docs for you that are vague and incomplete. Answer them the best way you can.

Problem 5: I am stuck with this critical bug/issue with my project. My time and energy are needed there. I can't focus on documentation right now

Well, you have struck gold. Writing down things as you work through an issue could not only help you solve it more efficiently, but could also help other teammates avoid the same pitfalls. It will help you solidify what you learned along the way. And you are recording your wins if you do end up fixing a critical issue, dear code hero. So document away, without feeling embarrassed.

Problem 6: I still don't know what to put into it

• Code snippets
• bash scripts
• command line
• sources that solved your problem
• technology stack details
• details about contributors ...just to get started

Write down any fresh ideas that pop up. You may or may not use them, but they could be useful.

You can always write detailed, accurate, stream-of-consciousness notes and then edit them for brevity.

It is up to you to decide what you get to put in and leave out, based on how relevant it is for those who might be reading it.

Problem 7: But my code is self-documenting

If your code is readable and the user can understand the purpose of the code, the battle is half won.

E.g. rust has a special kind of documentation comment, that can be used to generate HTML documentation for crates.

There would still be areas that need to be documented. Plus, comments might not get updated as rigorously as the code. Well-written documentation anticipates what the reader is looking for or thinking about next. So, the question is, "does this project have enough information tied to it so that another human being can understand it well enough?".

Problem 8: It is intimidating to start documenting my project

That is why I wrote this article. Blank pages, canvases or files can be intimidating, to begin with.

If you have a template for a similar project, don't hesitate to modify it (as long as you aren't violating any licenses that you need to be aware of.)

If it is a blank page, start by copying a snippet of what you already have: example code, comments, and names of the languages, frameworks, and databases.

Problem 9: I don't have the time to write documentation

There is never enough time. This is an unfortunate truth of our lives. It helps to squeeze in a few minutes for writing down things that you feel absolutely need to be remembered or understood for the sake of your project.

Start with 2 minutes a day. You might feel slow as a snail. Investing a few minutes is better than spending several hours later when you don't remember why you changed this configuration and installed that version of a library.

Problem 10: Yeah, but no one is going to read the documentation. Why bother writing it?

While it is important to keep your audience in mind as your write your docs, we have no control over what other people do or don't. If you know beforehand, who might be referring to the docs, you can put yourself into their shoes as you write.

Maybe zero other users read your docs and the docs you end up writing might benefit exactly one person, you. That is okay. Try not to take it personally if you think no one is reading them. We often can't say by whom or when it will be used, especially if you have tried your best.

People will come back (or you can direct them to your docs) when they eventually run into a problem that it would solve for them. Encourage your readers to develop a habit of referring (and possibly contributing to) documentation on their own.

Sensible versioning, accessibility and searchability can go a long way in making your documentation effective.

Problem 11: My docs are disorganised. Editing them is boring

Editing can be painfully boring. Sections do need to be renamed, reordered, or deleted as your project evolves. And like all projects, documentation is never complete. Check below about getting help from friends.

Problem 12: I still can't write .... Help! :|

Maybe you can dictate notes with your voice instead, create a visual guide with well-labelled diagrams, take up a technical writing course or barter with a friend who loves writing so that you do not need to deal with this awful exercise at all.

....

When you have put time and effort into your software project, documentation is a way to ensure that those efforts are not wasted.

If you have your own tips for making writing and maintaining docs less of a pain in the neck, let me know in the comments!

Share this article with others who would benefit from it. :)