Comment rédiger des documents techniques

1. Préparation Phase de préparation

Le travail en phase de préparation comprend principalement les points suivants :

·Exigences claires du document

·Clarifier l'audience du document

·Définir la portée du document

Avant de rédiger un document, cela doit être clair. Exigences en matière de documentation. Vous devez comprendre pourquoi vous souhaitez rédiger ce document et quel objectif vous souhaitez atteindre en rédigeant ce document.

Clarifiez également l’audience du document. Le contenu est susceptible d'être différent selon le public. Par exemple, la documentation destinée aux développeurs et aux non-développeurs/utilisateurs ordinaires aura une organisation de contenu différente.

Définissez également la portée du document. Réfléchissez et déterminez le contenu ou les modules que ce document doit couvrir et le contenu qu'il ne couvrira pas. De cette façon, vous aurez une certaine concentration lors de la collecte d'informations ultérieure, et elles ne seront pas vagues lors de la rédaction.

Recommandations associées : "Tutoriel d'introduction à PHP"

2.Étape de recherche

Ceux qui ont de l'expérience dans la rédaction de documents techniques. Les amis ressentiront certainement la même chose. Si vous ne comprenez pas quelque chose, rédiger une documentation à ce sujet est tout simplement trop pénible.

Alors, comment pouvez-vous éviter la douleur lorsque vous rencontrez un sujet inconnu dont vous n'avez aucune idée ? Bien sûr, je fais de mon mieux pour le comprendre.

Mais comment faire concrètement ? En bref, cela signifie collecter des informations. Alors comment collecter des informations ? L'auteur estime que nous pouvons partir des points suivants :

(1) Rechercher les documents pertinents de produits similaires plus représentatifs ou de produits similaires pour voir comment sont rédigés les documents d'autres personnes.

Quand on ne sait rien, c’est un bon choix d’apprendre des expériences et des pratiques des autres. En comparant la documentation de plusieurs produits, vous pouvez établir un cadre approximatif de la documentation que vous souhaitez rédiger.

Il convient de noter que la référence n'est pas une copie, elle est uniquement utilisée pour fournir des idées. Différents produits auront une planification structurelle différente du document ;

(2) Utilisez les méthodes les plus efficaces pour collecter toutes sortes d'informations liées au document que vous rédigez.

Les informations collectées feront probablement partie du document publié après avoir été extraites et organisées par le rédacteur technique.

Il existe de nombreuses façons de collecter des informations, telles que des recherches sur Internet, des questionnaires, des entretiens, des expériences, ainsi que des discussions par courrier électronique, des rapports, des articles techniques, etc. La méthode à utiliser nécessite une analyse détaillée. Vous devez choisir une méthode capable de collecter rapidement et précisément les données requises en fonction de facteurs tels que les exigences en matière de documents, les délais et la richesse des données existantes.

Sur certains sujets d'écriture, la recherche sur Internet peut ne pas être en mesure de vous apporter presque aucune aide. Même pour ce type de contenu, vous pouvez obtenir des informations auprès des développeurs. Vous pouvez leur demander de vous aider à fournir des informations en fonction de vos besoins, ou vous pouvez obtenir les informations dont vous avez besoin via des notes de développement et des discussions dans le système interne.

Pour la documentation d'un produit logiciel, même s'il existe des informations techniques, le rédacteur technique a souvent besoin de les utiliser lui-même, afin d'avoir une compréhension intuitive des étapes de fonctionnement et d'obtenir des informations de première main sur la rédaction du document.

3. Structure du document d'organisation

Lorsque les données sont presque collectées, vous pouvez organiser la structure spécifique de ce document. Des recherches antérieures sur des produits similaires peuvent être effectuées dans Voici. un coup de main.

Pour les guides d'utilisation courante des produits, ils sont généralement organisés par ordre d'installation ou d'utilisation ; pour les autres documents non-guides, ils doivent également suivre un certain ordre ou logique.

De plus, vous devez également vous demander si le document doit être accompagné d'images et si des tableaux doivent être utilisés. Si vous devez ajouter des images, indiquez clairement si vous avez besoin de l'aide des autres ou si vous devez les compléter vous-même. Dessiner un tableau plus complexe est également une tâche qui prend du temps, et le temps passé doit également être pris en considération.

Une fois que vous avez une structure détaillée du document, vous pouvez passer à l'étape suivante de rédaction.

4. Rédiger un document

Si vous avez bien fait les premières étapes, la rédaction deviendra très simple. Il vous suffira de remplir avec précision le contenu correspondant. dans le schéma du document. Dans ce processus, vous devez rédiger des paragraphes ou des étapes spécifiques. C’est le moment de réfléchir à vos compétences linguistiques et rédactionnelles.

Certains livres de rédaction technique disent que vous n'avez pas à vous soucier de la grammaire, de la formulation et de la ponctuation lors de la rédaction de documents, et pensent que ces détails devraient être améliorés lors de l'étape de révision.

Expand your outline into paragraphs, without worrying about grammar, refinements of language usage, or 
punctuation. 
Writing and revising are different activities; refinements come with revision. - Handbook of Technical 
Writing

J'ai une vision différente de cela. Un rédacteur technique qualifié doit avoir de bonnes compétences linguistiques. Les détails les plus élémentaires tels que la grammaire, la formulation et la ponctuation ne doivent pas être un problème à résoudre seul. Une grammaire standard, une formulation correcte et une ponctuation correcte auraient dû devenir une habitude d'écriture qui ne nécessite aucun effort supplémentaire et ne prend presque pas de temps supplémentaire.

Si la première ébauche est approximative et contient de nombreux petits détails qui doivent être modifiés, cela augmentera certainement la charge de travail et le temps nécessaire à la révision, retardant ainsi le processus de documentation.

Peut-être que cette méthode peut être adoptée pour les grandes entreprises qui ont une division du travail raffinée et où chacun n'est responsable que d'un petit maillon. Cependant, cela ne s'applique pas aux startups qui se développent rapidement et nécessitent un développement agile de la documentation.

5. Révision

Après avoir rédigé la première ébauche du document, celui-ci nécessite généralement une révision et une amélioration supplémentaires. La révision fait ici référence à la modification après révision, cette étape peut donc également être appelée : Révision et révision.

Alors, qui doit le réviser ? Les documents techniques nécessitent généralement deux types de revues de la part d'autres partenaires, à savoir :

·Revue technique : D'un point de vue technique, vérifier si la description dans le document est correcte et efficace

·Révision linguistique : vérifiez si l'expression dans le document est concise et appropriée au niveau linguistique

Après avoir reçu les commentaires du réviseur, le rédacteur technique doit porter des jugements et des modifications en temps opportun. . Tout point peu clair doit être discuté avec l'examinateur. Après avoir apporté les modifications, demandez au réviseur d’y jeter un œil. Si de nouveaux problèmes sont découverts, ils doivent être à nouveau révisés. Ce processus de révision-révision peut être répété plusieurs fois, ce qui est normal.

Bien sûr, avant de demander aux autres de le réviser, le rédacteur technique peut également le réviser lui-même pour éviter des erreurs de bas niveau et faire perdre du temps aux autres.

Haha, voici à nouveau le problème ~ Habituellement, les personnes qui viennent de terminer d'écrire un article sont très réticentes à lire ce qu'elles ont écrit. À ce stade, vous pouvez utiliser des outils de vérification de grammaire et d'orthographe pour vous aider. Vous l'avez.

Si vous pensez que vous êtes suffisamment prudent et que vous n’avez pas besoin de gadgets pour vous aider, j’admire vos capacités, mais je recommande quand même d’utiliser des gadgets. Parce que vous pouvez aussi avoir des moments où vous êtes en mauvais état, où vous êtes fatigué et assoupi, et parfois où vous ne savez pas ce que vous avez écrit... Ne soyez pas dur avec vous-même et vos gadgets.

6. Livraison du document Livraison

Une fois le document finalisé, il peut être publié sur la plateforme, qui est généralement simple à utiliser. Différentes entreprises disposent de différentes plates-formes de publication de documents et les outils de rédaction utilisés par les rédacteurs techniques sont également différents.

Une fois le document publié, cela ne signifie pas la fin. D'après mon expérience professionnelle, même les documents publiés peuvent encore rencontrer des problèmes, qu'il s'agisse de documents émanant de grandes ou de petites entreprises. Par exemple : des erreurs de texte non détectées, des liens rompus, des descriptions et des étapes qui ne correspondent plus aux derniers produits, etc. Le rédacteur technique doit suivre les développements de produits afin de mettre à jour les documents en temps opportun.

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!