Reference

Les guides de référence sont des descriptions techniques de la mécanique interne et de son fonctionnement. Les références sont orientées sur l’information.

---

Reference material contains propositional or theoretical knowledge that a user looks to in their work.

Le seul but d’un guide de référence est la description, aussi succincte que possible, de manière ordonnée. Alors que le contenu des tutoriels et des guides pratiques est dicté par les besoins de l’utilisateur, le matériel des guides de référence est défini par le produit qu’ils décrivent.

Dans le cas d’un logiciel, les guides de références décrivent le logiciel lui même - ses APIs, ses classes, ses fonctions, etc. - et comment les utiliser.

Vos utilisateurs ont besoin de matériel de référence parce qu’ils ont besoin de fiabilité et de certitude; des plateformes solides sur lesquelles ils peuvent s’appuyer durant leur travail. Une bonne référence technique est essentielle pour donner aux utilisateurs la confiance nécessaire dans leur travail.

---

Références en tant que description

Reference material describes the machinery. It should be austere. One hardly reads reference material; one consults it.

Il ne doit y avoir ni doute ni d’ambiguïté dans les références; elles doivent faire autorité.

Le matériel de référence est analogue à une carte géographique. Une carte vous donne les informations nécessaires à propos du territoire, sans avoir à vous déplacer ou à vérifier le territoire par vous-même. Un guide de référence poursuit le même objectif au sujet d’un produit et de sa mécanique interne.

Bien que la référence ne cherche pas à montrer comment effectuer des tâches, elle peut et doit souvent décrire le fonctionnement d’un objet ou la manière correcte de l’utiliser.

Unfortunately, too many software developers think that auto-generated reference material is all the documentation required.

Some reference material (such as API documentation) can be generated automatically by the software it describes, which is a powerful way of ensuring that it remains faithfully accurate to the code.

---

Key principles

Describe and only describe

Neutral description is the key imperative of technical reference.

Style and form

• sobre et sans compromis

• neutre, objectif, factuel

• structured according to the structure of the machinery itself

Unfortunately one of the hardest things to do is to describe something neutrally. It’s not a natural way of communicating. What’s natural on the other hand is to explain, instruct, discuss, opine, and all these things run counter to the needs of technical reference, which instead demands accuracy, precision, completeness and clarity.

It can be tempting to introduce instruction and explanation, simply because description can seem too inadequate to be useful, and because we do indeed need these other things. Instead, link to how-to guides, explanation and introductory tutorials.

Adopt standard patterns

Reference material is useful when it is consistent. Standard patterns are what allow us to use reference material effectively. Your job is to place the material that your user needs where they expect to find it, in a format that they are familiar with.

There are many opportunities in writing to delight your readers with your extensive vocabulary and command of multiple styles, but reference material is definitely not one of them.

Respecter la structure de la mécanique interne

La manière dont une carte correspond au territoire qu’elle décrit nous aide à l’utiliser pour trouver son chemin dans ce territoire. Il devrait en être de même avec une documentation: la structure de la documentation reflète la structure du produit, ainsi l’utilisateur s’y retrouve aisément.

It doesn’t mean forcing the documentation into an unnatural structure. What’s important is that the logical, conceptual arrangement of and relations within the code should help make sense of the documentation.

Offrez des exemples

Examples are valuable ways of providing illustration that helps readers understand reference, while avoiding the risk of becoming distracted from the job of describing. For example, an example of usage of a command can be a succinct way of illustrating it and its context, without falling into the trap of trying to explain or instruct.

---

Le style des guides de référence

Django’s default logging configuration inherits Python’s defaults. It’s available as django.utils.log.DEFAULT_LOGGING and defined in django/utils/log.py

Indiquez les faits concernant la mécanique et son comportement.

Sub-commands are: a, b, c, d, e, f.

Listez les commandes, options, opérations, caractéristiques, flags, limitations, messages d’erreur, etc.

You must use a. You must not apply b unless c. Never d.

Offrez des avertissements le cas échéant.

---

Applied to food and cooking

You might check the information on a packet of food, in order to help you make a decision about what to do.

When you’re looking for information - relevant facts - you do not want to be confronted by opinions, speculation, instructions or interpretation.

You also expect that information to be presented in standard ways, so that you - when you need to know about something’s nutritional properties, how it should be stored, its ingredients, what health implications it might have - can find them quickly, and know you can rely on them.

So you expect to see for example: May contain traces of wheat. Or: Net weight: 1000g.

You will certainly not expect to find for example recipes or marketing claims mixed up with this information; that could be literally dangerous.

The way reference material is presented on food products is so important that it’s usually governed by law, and the same kind of seriousness should apply to all reference documentation.