Computer Code Documentation

When you look back on code that you wrote six months ago, you may or may not remember why you did things in a certain way. Documentation allows you to transfer the why behind code. Much in the same way code comments explain the why, and not the how, documentation serves the same purpose.

Importance of Well-Written Documentation

There are many reasons why it’s important for you, as an IT professional, to apply good technical writing practices to writing code. Well-written documentation:

Enhances Usability

You have written a piece of code, and released it into the world. You have done this because you think that others might find it useful. However, people need to understand why your code might be useful for them, before they decide to use it. Documentation tells people that this project is for them. If people don’t know why your project exists,they won’t use it. If people can’t figure out how to install your code, they won’t use it. If people can’t figure out how to use your code, they won’t use it. There are a small number of people who will figure things out and use your code, but that is a small number compared to people who will use your code when properly documented.

Contributes to your Professional Community

Open source is this magical thing, right? You release code, and the code gnomes come and make it better for you. Not quite. There are lots of ways that open source is amazing, but it doesn’t exist outside the laws of physics. You have to put work in, to get work out. You only get contributions after you have put in a lot of work. You only get contributions after you have users. You only get contributions after you have documentation. Documentation provides a platform for your first contributions. A lot of people have never contributed before, and documentation changes are a lot less scary than code changes. If you don’t have documentation, you will miss out on a whole class of contributors.

Strengthens your code

It’s really easy to have an idea in your head that sounds perfect, but the act of putting words to paper requires a distillation of thought that may not be so easy. Writing documentation improves the design of your code. Talking through your API and design decisions on paper allows you to think about them in a more formalized way. A nice side effect is that it allows people to contribute code that follows your original intentions as well.

Enhances your Writing Skills

Writing documentation is a different form of writing than most people have experienced. Technical writing is an art that doesn’t come naturally. Writing documentation will start you down the road to being a better technical writer, which is a useful skill to have as an IT professional. Writing also becomes easier over time. If you don’t write for many months, it’s a lot harder to start writing again. Keeping your projects documented will keep you writing at a reasonable cadence.

What to Write

Make sure that you give your users all the information that they need, but not too much. First, you need to ask yourself who you’re writing for. At first, you generally just need to appeal to two audiences, users and developers. Users are people who simply want to use your code, and don’t care how it works. Developers are people who want to contribute back to your code.

README

Your first steps in documentation should go into your README. Code hosting services will render your README into HTML automatically if you provide the proper extension. It is also the first interaction that most users will have with your project. So having a solid README will serve your project well. Some people even go as far as to start your project with a README

basic example

This will render into a header, with a list underneath it. The URLs will be hyperlinked automatically. It’s easy to write, still makes sense as plain text, and renders nicely into HTML.

Explain the Problem your Project Solves

A lot of people will come to your docs trying to figure out what exactly your project is. Someone will mention it, or they’ll google a phrase randomly. You should explain what your project does and why it exists.

Provide a Small Code Example

Show an example of what your project would normally be used for.

Frequently Asked Questions (FAQ)

A lot of people have the same problems. If things happen all the time, you should probably fix your documentation or the code, so that the problems go away. However, there are always questions that get asked about your project, things that can’t be changed, etc. Document those, and keep it up to date. FAQs may become out of date, and do need updating, but when done well, they are a useful resource.

How to Get Support

Mailing list? IRC Channel? Document how to get help and interact with the community around a project.

Information for Potential Contributors

People usually have standards for how they expect things to be done in their projects. You should document these so that if people write code, they can do things in the norm of the project.

Installation Instructions

Once people figure out whether they want to use your code, they need to know how to actually get it and make it run. Write a few lines of installation instructions as a basis. If you need to provide more information, link to it.

License

BSD? MIT? GPL? This might not matter to you, but the people who want to use your code will care about this. Think about what you want to accomplish with your license, and please choose only of the standard licenses that you see described online.

Structure for Computer Code Documentation

Soham Kamani provides a clear structure in his blog post on How to Write Good Documentation (And Its Essential Elements); please link to and read his page, which discusses the following: [1]

  • Title
  • Short Description
  • Getting Started – includes installation instructions and sample code
  • Tutorials
  • Sample Projects
  • API Reference
  • Architecture Documentation

For fuller information about headers, naming conventions within the code, and comments within the code, read the following pages:

 

[1] Kamani, S. How to Write Good Documentation (And Its Essential Elements). https://www.sohamkamani.com/blog/how-to-write-good-documentation/.