How to Write Great Documentation

It doesn't make a difference how great your software is if the documentation isn't up to the mark. People won't use it! Even if they have no choice but to use your software, without great documentation, they won't use it adequately or in a way you'd like them to.

Almost everyone understands that great documentation is imperative, and numerous documentation maintainers attempt to work on it as well. However, most of them fail. Most of the time, it is not because they don't make enough of an effort. They are just not doing it in the correct manner. In this article, we will clarify how you can improve your documentation, not by working harder at it, but by doing it the correct way. The correct way is the simpler way - simpler to compose, and simpler to keep up with. There are some basic rules that administer documentation. However, they are not known by many people (even though they should be). Implementing these standards will improve your documentation and your venture, product or group greatly - that is a guarantee!

The secret to writing great documentation

Documentation needs to incorporated and organized around its functions: tutorials, how-to guides, explanations, technical reference guides, and user guides. Every one of them requires a particular method of composing. All these functions must be kept separate from each other though. A tutorial, for instance, is different from how-to guides where the former is learning--oriented, allows the newcomer to get started, and acts as a lesson. The latter is more goal-oriented and provides a solution to a specific problem through a series of steps. Similarly, explanations are different from, reference guides. They are understanding-oriented by providing explanations, a background, and context. Reference guides, however, are information-oriented that describe machinery accurately and completely. This division makes it evident to both the writer and reader what data goes where. It advises the writer how to compose, and what to compose, and where to compose it. It spares the writer from squandering most of his time attempting to wrestle the data he needs to give into a shape that is sensible because each of these documentations types have one job.

Project Documentation

You may well ask: where do things like change-logs, contribution policies, and other data about the project fit into this plan? The appropriate response is that they don't, in light of the fact that they are strictly just projected documentations as opposed to a documentation of the product itself. They can simply be kept in suitably (named sections along with relevant material) as long as they are not mixed up in it. Keeping this in mind, let’s go through the major functions!

Tutorials

Tutorials are exercises that take the reader by the hand through a series of steps to finish a project or something similar. They are completely learning-focused. You are the teacher, and you are in charge of what the student does. Under your guidance, the student will execute a progression of activities. The end and the activities are up to you but choosing what they should be can be hard work. The end must be meaningful, but attainable for the beginner. Think about teaching a child to cook. What you show the child to cook isn't generally essential. What's vital is that the kid thinks that it’s fun, and gains confidence, and wants to do it again! Most software projects have downright awful - or non-existent - tutorials. Tutorials are what will transform your learners into clients. Great tutorials are hard to make. They should be helpful and simpler for the beginner.

How-to guides

These are user-guides that help a user to solve real-world problems. They are like recipes which consist of directions to achieve a goal. This implies that they are goal-oriented. For instance, how-to guides like ‘How to create a web form’ help the users to create real problems. Good how-to guides provide the user with steps to follow. Secondly, they should focus on the results. Anything else is just a distraction! Moreover, it should address a specific question or problem. A how-to guide doesn’t explain things. Rather, it will provide steps assuming that you know how things work. They are also flexible for the users and are named specifically according to the needs of the users!

Explanation

Explanations can be described as discussions. They clarify and illuminate a particular topic and broaden the documentation’s coverage of a topic. Good explanations provide background and context – for instance, ‘Search and Django CMS.’ Moreover, they discuss alternatives and different approaches to one question. They don’t construct, or provide technical references! It is not their job to do things that other parts of the documents do not.

References

Reference-guides are most useful for someone who’s working. They provide theoretical knowledge and are information oriented, like encyclopedias. You can only refer to them to validate your work.

How to make documentation work

One of the biggest issues documentation maintainers come across is not having a vivid idea of what they are doing. The structure, however, acts as an aid and helps them organize their documentation to make them great and helpful! When a developer lands on your documentation homepage, they are typically curious about what you are offering, willing to get started, or are stuck and need help immediately. User-guides should also be language specific so that more developers can access it. Good documentation also allows feedback from its customers to ensure that they are directly catering to the needs of the people. API References will allow the developers to leave the documentation and work on their implementation. When they return, they will come to answer a specific question which they will usually find in their API references. Moreover, speaking a developer’s language is one strategy that gets them started faster! Another way is to give them a code that the developers can easily copy and paste. You can find numerous examples of documentation where the code is almost ready to use. This will make your document great to use!