A Friendly Intro To Software Documentation

Documents are such an underrated thing. We all love good documentation when we see one, but when it comes to writing our own documentation, that's where it gets tricky!
Today we're going to discuss documentation, its role in software and development, and why it's better to spend company resources to create and maintain it.

Why Documentation?

There has always been a love-hate relationship between developers and documentation. We love it when we consume it, and it's the most difficult thing to make at the same time. Because everybody knows, right? Or, good code documents itself. We've all heard these infamous lines somewhere down the road. Maybe at some point, we thought to ourselves, "Well, the code I have written seems pretty easy. How can someone not understand this?"
While that may be true in some cases, it often causes more trouble than it seems.
Documentation helps keep track of where the project is headed while preserving its current and past state.

Project

There are many stages in the project's lifetime. Some of them can include meetings with the stakeholders. Documents help clearing the air by providing transparency about:

• The project
• Where it is headed
• Its current state

It eases the process of change in the project, which can be a change of managers, features, developers, etc.

Development

Developers use documentation all the time. You don't have to be a major company to use documents. Suppose you are a small team of developers with a few people in each section (front-end, back-end, infrastructure, etc.). Having documentation in each section helps other teams manage their work with less entanglement between people.
John doesn't have to call Ellis to ask about the project APIs or ask for a sample request to call a service. With proper documentation, he can simply look up the documentation for that service and get most of the data he needs.

Speeding Up Recruitment

It's much faster and easier to read documentation about something rather than having to look for someone to explain it. When there are new employees in the company, it is very convenient to have them read the documentation because:

1. It saves company resources. This way, the company doesn't need to assign another employee to get the newcomers up to date with everything.
2. It is up-to-date with the company's projects and latest developments.
3. It has enough information a newcomer needs to get started.
4. It allows them to get familiar with the working environment and how projects are handled in the company.
5. It can be a faster approach because people might learn faster if they do it at their own pace.

Make Better Documents

Now that we know why we should use documents, there are a few things we can keep in mind to make better documentation.

Implement Documentation in your Development Cycle

Starting documentation for a project can be a huge thing. Specially if the project has been going on for some time. The first thing to understand is that:

Documentation is a part of software development.

So don't think little of it. It is something that needs its own dedicated time during development, and for good reason. So don't think that it is something that can be done in a few days, and you're done. No.
In order to have useful and effective documentation, you need to implement it in your development cycles/sprints/iterations. Dedicate a part of your company's employees time to documentation, and don't make it sound unimportant. Sure, you'd like to get that feature done quickly, but you also need to have that feature documented so the next person working on it can have an easier time developing it. 

Think Outside the Box

I was reading a book on software documentation. It mentioned something very important when writing software documentation, The Curse Of Knowledge. When you are writing documentation about something, you have a certain level of understanding about it. You don't need to be the master of that thing, just enough to make others understand too. But when we are transferring knowledge, we tend to forget that other don't know. 
"It's such an easy thing; how can someone not get it?"
But we easily forget the amount of energy and time we put into learning something. So it's easy to overlook important things in the document and miss out on a few things here and there. These things add up, and suddenly we find ourselves with a piece of vague documentation that creates more questions than it answers.
In order to avoid this tricky situation, here are some things you should consider before writing documentation:

• Who are you writing the document for?
• What is their level of knowledge? What is the prerequisite for this document?
• What kind of information are you trying to transfer? Is it a tutorial? a reference? a starting guide?
• What can the audience do wrong? for example, if they click on another button, fill out the wrong form, or enter the wrong information? Keep everything in mind.

Don't Overthink It

Writing documentation is not rocket science. However, it easily gets overwhelming when we think about all the things we want to write. It's important to write just the right amount of documentation, but at the same time, it can get out of hand very quickly. Try to have your documents reviewed by multiple people, like the audience you are writing for.
For example, if you are writing documents for a customer, have them read them and tell you if they have any problems with them. Or have someone who knows the topic read it.

Feedback always helps. 

Try not to bombard the reader with too much information. Keep it just enough, but don't forget the edge cases of what they should know and should not.

Final Words

While writing software documents can be a slow and boring task for many, it is almost always worth it. Don't let anyone tell you otherwise. It can cost you, but developing good software comes with costs.
I hope this article has helped you find your way with documents.