Guide de style

Des utilisateurs très divers, notamment des professionnels de l’informatique et des développeurs, lisent les documents .NET en vue d’apprendre à utiliser .NET dans leurs tâches quotidiennes. Votre objectif est de créer une documentation qui accompagne les lecteurs. Notre guide de style a pour but de vous y aider. Il contient les recommandations suivantes :

Utilisez un style oral

Le paragraphe suivant est écrit dans un style conversationnel. Celui qui suit est écrit dans un style plus académique.

Style approprié

Nous souhaitons que notre documentation emploie un style oral. Le lecteur devrait avoir l’impression d’avoir une conversation avec l’auteur lors de la lecture d’un tutoriel ou d’explications. L’expérience doit être informelle, conversationnelle et informative. Le lecteur doit avoir l’impression qu’il écoute l’auteur lui expliquer les concepts.

Style inapproprié

Il existe un contraste entre le style oral et le style des rubriques techniques au traitement plus académique. Ces ressources sont très utiles, mais leurs auteurs ont écrit ces articles dans un style très différent de celui de notre documentation. Une revue académique emploie un ton et un style rédactionnels totalement différents. On a généralement la sensation de lire une rubrique avec un ton très sec.

Écriture à la deuxième personne

Le paragraphe suivant utilise la deuxième personne. Celui qui suit utilise la troisième personne. Veuillez écrire à la deuxième personne.

Style approprié

Écrivez vos articles comme si vous vous adressiez directement au lecteur. Le plus souvent possible, utilisez la deuxième personne (comme dans ces deux phrases). Mais le terme « deuxième personne » ne veut pas toujours dire utiliser le mot « vous ». Écrivez directement au lecteur. Écrivez des phrases à l’impératif. Dites au lecteur ce que vous voulez qu’il apprenne.

Style inapproprié

Un auteur pourrait également choisir d’écrire à la troisième personne. Dans ce modèle, il doit trouver un nom ou un pronom à employer pour faire référence au lecteur. Le lecteur trouvera souvent ce style moins agréable à lire.

Utilisez la voix active

Rédigez vos articles à la voix active. Le terme « voix active » signifie que le sujet de la phrase effectue l’action (verbe) de cette phrase. Par contraste, une phrase à la voix passive est organisée de telle sorte que le sujet de la phrase subit l’action. Comparez ces deux exemples :

Le compilateur a transformé le code source en exécutable.

Le code source a été transformé en exécutable par le compilateur.

La première phrase utilise la voix active. La deuxième phrase a été rédigé à la voix passive. (Ces deux phrase fournissent un autre exemple de chaque style.)

Nous recommandons l’utilisation de la voix active car elle est plus agréable à lire. La voix passive peut être plus difficile à lire.

Écrire pour des lecteurs qui peuvent avoir un vocabulaire limité

Vos articles sont destinés à une audience internationale. La langue maternelle de la plupart de vos lecteurs n’est pas l’anglais. Ces lecteurs n’ont peut-être pas le même niveau de vocabulaire en anglais que le vôtre.

Mais d’un autre côté, vous écrivez tout de même pour des techniciens. Vous pouvez partir du principe que vos lecteurs ont des connaissances en programmation et du vocabulaire propre aux termes de programmation. Des termes tels que programmation orientée objet, classe, objet, fonction et méthode leur seront familiers. En revanche, tous vos lecteurs ne seront pas titulaires d’une licence en informatique. Vous devrez probablement définir des termes tels que « idempotent » si vous les utilisez, par exemple :

La méthode Close() est idempotente, ce qui signifie que vous pouvez l’appeler plusieurs fois et l’effet sera le même que si vous l’aviez appelée une seule fois.

Évitez d’employer le futur

Dans certaines langues, le concept du futur comme temps verbal n’est pas le même qu’en anglais. L’emploi du futur peut accroître la difficulté de lecture de vos documents. De plus, quand on emploie le futur, la question évidente est « quand ? ». Ainsi, si vous écrivez « L’apprentissage PowerShell vous sera bénéfique », le lecteur se posera la question évidente « Quand cela sera-t-il bénéfique ? ». Au lieu de cela, dites simplement : « L’apprentissage PowerShell est très utile ».

Qu’est-ce que c’est ?

Chaque fois que vous introduisez un nouveau concept, définissez-le d’abord. Ensuite, expliquez pourquoi il est utile. Le lecteur doit d’abord comprendre de quoi il s’agit avant de pouvoir en comprendre les avantages (ou inconvénients).