How to write technical documents

Documentation is translated from What nobody tells you about documentation.

There should be four elements to writing a good software document, not one. They are: tutorials, instructions, instructions and technical references. They represent four different purposes and functions, and four different approaches are required to create them. Knowing what this means can help improve most software documentation – often with great results.

preface

It doesn’t matter how good the software is, because if the documentation isn’t good enough, people won’t use it.

Even if for some reason they have to use it, it’s because they don’t have a choice, without good documentation, they won’t use it effectively or the way you like it. Almost everyone knows this. Almost everyone knows they need good documentation, and most people try to create good documentation. But most of them failed. It’s usually not because they don’t try hard enough, but because they don’t find the right way.

In this article, I’ll explain how to make your documents better, not by trying harder, but by doing it right. The right way is the simpler way – easier to write and easier to maintain.

There are some very simple principles for managing rare spelled documents. They seem to be a secret, though they shouldn’t be. If you can put these principles into practice, it will make your documentation better and your project, product or team more successful — that’s a promise.

The documentation needs to contain and be built around four different features: tutorials, how-to guides, instructions, and technical references. Each of them needs a unique mode of writing. People using software need these four different documents in different environments – so they are often needed in software. Documents need to be explicitly built around them, and they must remain separate and distinct from each other.

The tutorial	Operational guidelines for school official cites use	instructions	Technical reference
Be learning-oriented	Be goal-oriented	Be understanding oriented	Be information oriented
Allow newcomers to get started	How do you solve a particular problem	explain	Describe the software
It’s a course	It’s a series of steps	Provide context and context	It is accurate and complete

This division makes it clear to the writer and the reader what information is where. It tells the author how to write, what to write, and where to write it. It saves authors from wasting a lot of time trying to tamper the information they want to convey into a meaningful shape, because each of these documents only has one job.

In fact, well-maintained documentation makes it very difficult to implicitly or unambiguously identify the quadrants of the schema. Each type of requirement is different from the others, so any attempt to document that fails to maintain this structure is affected because it is immediately pulled in a different direction.

Once you understand the structure, it becomes a very useful tool for analyzing existing documentation and understanding what needs to be done to improve it.

You may ask about the project files: How do change logs, contribution policies, and other information about the project fit into this scenario? The answer is they don’t — because technically, they’re project documentation, not documentation of the software itself,

They can simply be stored in appropriately named sections with other materials – as long as they are not mixed together.

With that in mind, let’s explore each of the four key features.

The tutorial

A tutorial is a course that takes the reader through a series of steps to complete a project. They are what your project needs to show beginners that they can achieve something with it.

They are totally learning-oriented; specifically, their goal is to learn how rather than learn.

You’re the teacher. You’re in charge of the students. Under your guidance, students will perform a series of operations to achieve their goals.

It’s up to you to finish and act, but deciding what they should do can be hard work. It has to make sense eventually, but it’s achievable for a complete beginner.

Consider a metaphor for teaching a child to cook.

It doesn’t matter what you teach your children to cook. The important thing is that the child finds it fun and has confidence and wants to do it again.

Through the things the child does, it will learn the important things about cooking. It will learn what it’s like to use cutlery to handle food in the kitchen.

This is because using software like cooking is a matter of skill. It is knowledge – but it is practical knowledge, not theoretical knowledge. When we learn a new craft or skill, we always start learning it.

It is important that, after completing the tutorial, learners understand the rest of the documentation and the software itself.

Most software projects have very bad or non-existent tutorials. Tutorials will turn your learners into users. An error or missing tutorial will prevent your project from acquiring new users.

Good tutorials are hard to write. They need to be useful for beginners, easy to follow, meaningful, and extremely robust.

Allow users to learn

In the beginning, we learned everything by doing — that’s how we learned to talk or walk.

Things your learners need to do in your software tutorials. The different things they do as they work through this tutorial need to cover a wide range of tools and operations, starting with the simplest and moving on to more complex ones.

Get the user started

If your beginner’s first step is a hand-held baby step, this is perfectly acceptable. If the beginner is not doing it the experienced person’s way, or even if it is not the “right” way, that is perfectly acceptable – the beginner’s tutorial is different from the best practices manual.

The purpose of a tutorial is to get learners started on their journey, not to get them to their final destination.

Please confirm your tutorial works

As a mentor, one of your jobs is to inspire confidence in the beginner: in the software, in the tutorials, in the tutors, and, of course, in their ability to achieve what is required on their own.

There are many things that can contribute to this. Friendly tone and consistent use of language and logical progression of material help. But most importantly, what you’re asking a beginner to do must work. Learners need to see that the actions you ask them to take will produce the results you say they will.

If the learner’s actions produce errors or unexpected results, your tutorial will fail – even if it’s not your fault. When your students are with you, you can save them; You can’t if they read your document themselves – so you have to prevent that in advance. No doubt this is easier said than done.

Make sure users get results immediately

Everything the learner does should be understandable, no matter how small. If your students have to do two pages of strange and incomprehensible things before they see the results, that’s too long. The effects of each action should be visible and evident as soon as possible and should be clearly linked to the action.

Each part of the tutorial or the conclusion of the entire tutorial must be a meaningful achievement.

Make the tutorial repeatable

Your tutorial must be repeated reliably. This will not be easy to implement: people will use different operating systems, experience, and tool levels to implement it. What’s more, any software or resources they use are likely to change during that time.

Each tutorial must apply to all of them.

Unfortunately, tutorials require regular and detailed testing to ensure they are still valid.

Focus on concrete steps, not abstract concepts

Tutorials need to be specific, centered around specific, specific actions and outcomes.

The temptation to introduce abstraction is great; After all, that’s how most computing gets its power. But all learning goes from the specific, concrete to the general and abstract, and requiring learners to appreciate the level of abstraction before they have even had a chance to master the concrete is bad teaching.

Provide the minimum necessary explanation

Don’t explain anything the learner doesn’t need to know in order to complete the tutorial. Extending the discussion is important – just not in the tutorial. In the tutorial, this is a barrier and distraction. Only the minimum is appropriate. Instead, link to explanations elsewhere in the document.

Focus only on the steps the user needs to take

Your tutorial needs to focus on the task at hand. Perhaps the command you introduced had many other options, or there might be different ways to access an API. That’s okay: Right now, your learner doesn’t need to know that to make progress.

Operational guidelines for school official cites use

The instructions give the reader an idea of the steps needed to solve a real-world problem.

They are recipes, directions for achieving a specific goal – for example, how to create a Web form; How to draw 3d data sets; How to enable LDAP authentication.

They are totally goal-oriented.

If you want a metaphor, think of a recipe for getting ready to eat.

Recipes have well-defined endings. It solves a specific problem. It shows how someone – one can assume he already has some basic knowledge – can achieve certain goals.

Instructions are completely different from tutorials. How-to guides are answers to questions that a true beginner can’t even formulate.

In the instructions, you can assume some knowledge and understanding. You can assume that users already know how to perform basic operations and use basic tools.

Provide a series of steps

The instructions must contain a list of steps that need to be performed in sequence (just like a tutorial). You don’t have to start at the beginning, just at a reasonable starting point. Instructions should be reliable, but they do not require the repeatability of tutorial cast iron.

Focus on results

Guidelines must focus on achieving practical goals. Anything else is a distraction. As with the tutorial, detailed instructions are not appropriate here.

To solve the problem

Guidelines must address specific problems or questions: How do I… ?

This is one way that the how-to guide differs from the tutorial: when it comes to the how-to guide, it can be assumed that the reader knows what they should implement, but not yet how – whereas in this tutorial, it is your responsibility to decide what the reader needs to know.

Don’t explain concepts

Instructions should not explain things. This is not the place for that kind of discussion; They just get in the way. If explanations are important, link to them.

Allow some flexibility

The instructions should allow for slightly different ways of doing the same thing. It needs to be flexible enough that the user can see how it will be applied to a slightly different example than the one you describe, or see how it can be adapted to a slightly different system or configuration than the one you assume. Don’t be so specific unless you have the exact purpose in mind. A guide is useless for anything.

At any time to leave

Actual usability is more valuable than integrity. Tutorials need to be complete, end-to-end guides; Operation guide no. They can start and end where it suits you. They don’t need to mention everything, just because it’s relevant. Bloated operation guides cannot help users quickly obtain solutions.

The title is user-friendly

The title of the method document should tell the user exactly what it is. How to create class-based views is a good title. Creating class-based views or worse, class-based views are not.

Technical reference

The technical reference is the technical description of the machine and how to operate it.

Technical references have only one job: description. They are determined by the code, because they ultimately describe: key classes, functions, apis, and so on. They should list functions, fields, properties, methods, and so on, and list how to use them.

Resources are information-oriented.

In various ways the technical reference can contain examples to illustrate usage, but it should not attempt to explain basic concepts or how common tasks are achieved.

References should be rigorous and to the point.

A culinary analogy might be a global article about an ingredient, describing its origin, its behavior, its chemistry, how it’s cooked.

Note that the description does include a basic description of how to use the machine – how to instantiate a particular class, or call a method, or the precautions you must take when passing something to a function. However, this is only part of its function as a technical reference, and it is emphasized not to be confused with an instruction manual – describing the proper use of the software (a technical reference) is different from showing how to use it for a purpose (a method document).

For some developers, the reference guide is the only documentation they can imagine. They already know their software, they know how to use it. They can imagine that what other people might need is technical information about it.

Reference materials are often well written. It can even be generated automatically to some extent, but that in itself is not enough.

Build documentation around the code

Provide the reference document with the same structure as the code base so that users can navigate both code and documentation. This will also help the maintainer see where reference documents are missing or need to be updated.

Always the same

In technical references, structure, tone, and format must be consistent – as in an encyclopedia or dictionary.

Don’t make any description

The only job of a technical reference is to describe it as clearly and completely as possible. Anything else (explanation, discussion, guidance, speculation, opinion) not only distracts, but also makes it harder to use and maintain. Provide examples to illustrate where appropriate.

Avoid using reference materials to guide you on how to implement things, beyond the basic scope of using software, and do not allow explanations of concepts or discussions on topics. Instead, link to how-to guides, instructions, and tutorials as appropriate.

accuracy

These descriptions must be accurate and up-to-date. Any discrepancy between the machine and your description of it will inevitably lead users astray.

instructions

To illustrate or discuss, illuminate and illuminate a particular subject. They broaden the document’s coverage of a topic.

They are understanding oriented.

Explanations can also be described as discussions. They are an opportunity for the document to relax and retreat into the software, to clarify it from a broader perspective, at a higher level or even from a different perspective. You can imagine a discussion document that is read at leisure, not on code.

This part of the document is rarely explicitly created; instead, explained fragments are scattered among other sections. Sometimes the section exists but has a name, such as background or other notes, that doesn’t really do justice to the function.

Discussions are not as easy to create as they seem – something that explains directly is not so easy when you have a starting point for a question, when you have a blank page and have to write something about it.

A topic is not defined by a specific task you want to implement, such as a how-to guide, or something you want users to learn, such as a tutorial. It’s not defined by a piece of machine, like reference material. It is defined by what you think is a reasonable area to cover in an attempt, so the division of discussion topics can sometimes be a little arbitrary.

Provide context

The instructions are the location of the background and context – for example, Web forms and how to handle them in Django or Search and Django CMS.

They can also explain why things are the way they are – design decisions, historical reasons, technical limitations.

Discuss alternatives and suggestions

Explain that alternatives, or many different approaches to the same problem, can be considered. For example, in an article on Django deployment, it’s appropriate to consider and evaluate different Web server options,

The discussion can even consider and weigh opposing opinions – for example, whether the test module should be in the package directory.

Do not instruct or provide technical references

State what should be done that is not in the rest of the document. Telling the user how to do something is not the place to explain. Nor should it provide a technical description. These functions of the document are dealt with in other sections.