The staple of this article is to share the observations and raise awareness on why developer documentation is important to the software project and its people.

Who should read this article?

- anyone who identifies themselves as a coder, programmer or developer, plus the ones who are sad and anxious to hear the word 'documentation'.

Why would you spend your precious time writing documentation?

Here are some legit reasons to spend your precious time on documentation:

  1. Good documentation saves you a significant amount of time and effort.
  2. Code and documentation are good neighbours. Always build it strong.
  3. Write documentation while you are writing your code. You are your first reader.
  4. Try to explain to yourself what you are doing to your code. Future you will be happy with yourself.

Eh! Still not interested? Here are some more.

You will reuse your code sooner than you even realize.

Life would be much simpler if you wrote down why you coded that in the first place. Documentation helps you remember the 'why' part behind your code. Think of it as an extended version of code comments.

You want peer developers to use your code.

  • If peers don't know why your project exists, they won’t use it.
  • If peers can't figure out how to set up your code, they won't use it.
  • If peers can’t figure out how to use your code, they won’t use it.

So it is better to stop creating hurdles for your peers and start writing your part of what you did to help expedite the process of onboarding the project.

You want your codebase to be better.

A codebase with proper documentation is better than software without a bug. Well-documented writing of the architecture and design of the codebase makes it easier and minimizes the risks of common pitfalls. Maintaining and improving documentation in an open source community is also fruitful. It is a perfect way to attract open source contributors with a similar interest in your project to adapt and grow.

You want to be a better developer.

As a software developer, you should thrive on writing and maintaining documentation over the project's lifespan and even more time to improve it. There should be a pedagogical basis for analyzing the developer documentation. A peer developer should be professing the concepts and understanding of the project to a bunch of other peers.

Make a habit of taking notes. Easy as it could sound.

An iterative note-taking habit of important details during or after you complete a coding session reaps fruitful in the long run. Some of the common things you can include in your notes may be but are not limited to:

  • terminal commands, bash scripts and automation modules (*.sh files)
  • zero-day bug, critical severity issues and workaround patches
  • web links, images, videos, assets, and other online resources
  • code snippets, logfiles, dependencies, configs etc.

Write a longer version of the short notes. Be your rubber duck. Explain to yourself what you are doing, why it was needed and how you will do it again so that it becomes easier. Be your teacher and teach yourself; pretty well. Use comments and complete sentences that make sense at a glance so that the description, which was meant to help you, should not be a burden to understand when you see it after a month or even a year.

Include the most important prerequisite knowledge of the project you are working on. You might be working on many kinds of programming tools and tech stacks most of the time. You will also switch among those tools and stacks frequently. It will be easier to forget and harder to remember every minute detail. Hence write down README, installation steps, usage, issue reports, architectural design patterns and more.

KISS. Keep It Short and Simple.

KISS is a common acronym in the programming community. Avoid jargon, acronyms, and technical words that your readers might find difficult to understand. If it is necessary, explain it. Shorter notes and compact documentation are easier to read and understand. Value your reader's time. Remove unwanted words or repeated sentences. Remember, every detail you write should serve a purpose and make sense.

Structure your document in a well-fashioned manner. Style matters.

Well-structured documents are easier and quicker to navigate around the content. Don't shy away from using the following features.

Text Formatting Tools

For example:

  • Use headings to group your ideas and set the hierarchy of your content.
  • Use bold, italics, underlined and other relevant formats to present your idea. Get the most out of these tools.

Use visuals wherever possible. Reduces time and effort for readers.

"A picture speaks a thousand words". Even better, you can use animated GIFs or videos to enhance your readers' experience. Just an addition of an image creates a huge difference in the readability.

The only mantra to improve; Read, Write and Rewrite

Good readers are good writers. Read a lot and observe the good and the bad aspects of that writing. Just learning theories won't help you much. The best way to learn "writing documentation" is by writing. Your writing won't be perfect, and that's where rewriting comes in. You need to edit your draft continuously to refine it.

I edit and update this article timely for corrections and improvements. Thank you for reading.