Recommended
Recommended
More Related Content
What's hot
What's hot (11)
Similar to Technical writing human talk
Similar to Technical writing human talk (20)
Recently uploaded
Recently uploaded (20)
Technical writing human talk
- 1. Technical writing – Human Talk By Lucas Girardin
- 2. 2 salles – 2 ambiances • Public documentation @ Microsoft For services/consulting @PykPyky
- 3. 2 salles – 2 ambiances • Public documentation @ Microsoft For services/consulting • Internal documentation @ Axway To run internal application @PykPyky
- 4. Technical writing a skill, realy? • Technical writing definition: Writing or drafting technical communication used in technical and occupational fields, such as computer hardware and software, engineering, chemistry, medical… • Skills to have: Write clearly in English. Learn complex technologies relatively quickly. Explain complex technologies in useful ways for the target audience. Wield strong interpersonal skills. Understand code. @PykPyky
- 5. Technical writer a job, realy? • Around 180 jobs open in France • More than 3.400 in EMEA • More than 6.700 in United state • More than 15.000 worldwide • Technical writers plan, create, and maintain educational content as an integral part of the engineering or user experience. The content is often in the form of documentation, but may also be UI text, sample code, videos, or other educational material. @PykPyky
- 6. Importance of technical writing skills • Most valuable transfer knowledge tool Asynchronous Searchable • We pass more time reading documentation than write it Like code • We have all different way to write and explain, that why technical documentation must have a guideline/convention Like code again @PykPyky
- 7. Explain a term • Why ? You cannot expect that the audience know all terms you will use You cannot explain all terms in documentation (Otherwise it’s a glossary) • The solution! You must know with a term that can be unfamiliar for the audience and must be explained or not You must explain a term directly after the introduction or with a link to the glossary • Example : SecureTransport (ST), is the File Exchanging component between customers and Axway The customer connects to ST though a web interface, that is HTML page @PykPyky
- 8. Prefer active voice • Why ? Passive voice obfuscates your ideas and reports action indirectly. Mentally, you usually convert passive voice to active voice Some passive voice sentences omit an actor Passive voice is usually longer than active voice • Solution ! Good sentences in technical documentation identify who is doing what to whom An imperative verb is typically active • Example : Open the file configuration Set the modeVariabilisation variable to false @PykPyky
- 9. Choose strong verbs • Why? Reuse only a small set of mild verbs to make all your sentence similar, you don’t want to serve lettuce every day Generic verb reduce clarity and commitment It uses generally with passive voice • Solution ! Pick the right verb and the rest of the sentence will take care of itself. It takes a little more time but produces more satisfying results. Avoid: forms of be (is, are, am, was, were, etc.), occur, happen • Example : The error occurs when clicking the Submit button. Clicking the Submit button triggers the error. This error message happens when... The system generates this error message when... We are very careful to ensure... We carefully ensure... @PykPyky
- 10. Other general good practice • Don’t change a name • Use acronym or pronoun carefully • Reduce there is/there are • Minimize adjectives and adverbs • Eliminate words @PykPyky
- 11. Do list or table and do it good • Example 1: The lamacatcher API enables callers to create and query lamas, analyze alpacas, delete vicunas, and track dromedaries. The lamacatcher API enables callers to do the following: Create and query llamas. Analyze alpacas. Delete vicunas. Track dromedaries. • Example 2 Nonparallel carrots potatoes The summer light obscures all memories of winter. Parallel Carrots contain lots of Vitamin A. Potatoes taste delicious. Cabbages provide oodles of Vitamin K. @PykPyky
- 12. Paragraphe – One paragraphe, one topic • Why ? Long paragraphs are visually intimidating Readers generally welcome paragraphs containing three to five sentences, but will avoid paragraphs containing more than about seven sentences If your document contains plenty of one-sentence paragraphs, your organization is faulty • Solution Restrict each paragraph to the current topic, don't describe what will happen in a future topic or what happened in a past topic Consider dividing very long paragraphs into two separate paragraphs Combine one-sentence paragraphs into cohesive multi-sentence paragraphs or into lists Good paragraphs answer the following three questions: What, why, how • Example : The garp() function returns the delta between a dataset's mean and median. Many people believe unquestioningly that a mean always holds the truth. However, a mean is easily influenced by a few very large or very small data points. Call garp() to help determine whether a few very large or very small data points are influencing the mean too much. A relatively small garp() value suggests that the mean is more meaningful than when the garp() value is relatively high. @PykPyky
- 13. But also… • Fit to your audience • Define prerequisite knowledge • Define prerequisite documents • Define scope and non-scope @PykPyky
- 15. • Frambus System communication owerview @PykPyky
- 17. • Images: Are there images next to the text to help people understand what the text is about? • Sentence: Are the sentences 1 or 2 lines long? • Words: Are the words simple? • How the information is ordered: Is the main information easy to find? Is each paragraph about one topic? Are bullet points used for lists? When the text says he or she, is it clear who it is talking about? @PykPyky
- 18. Easy-to-read / FALC • Images: Are there images next to the text to help people understand what the text is about? • Sentence: Are the sentences 1 or 2 lines long? • Words: Are the words simple? • How the information is ordered: Is the main information easy to find? Is each paragraph about one topic? Are bullet points used for lists? When the text says he or she, is it clear who it is talking about? @PykPyky
- 19. Take away • Microsoft Writing style guide • Google developer documentation style guide • Google Overview of technical writing courses • App diagram • UML Diagrams: Versions, Types, History, Tools, Examples • Blog post about FALC by Anne-Sophie • More content on twitter soon @PykPyky @PykPyky
Editor's Notes
- Bonjour à tous et toute, je suis Lucas Girardin, et aujourd’hui je vous parler de documentation technique et de leur rédaction.
- Vu que je n’ai que 10 minutes pour vous parler d’un sujet aussi passionnant et vous dire qui je suis vais faire les deux en même temps. J’ai commencé, en faisant du consulting pour les clients Microsoft. J’étais l’expert Office 365 et on me posait des questions sur les nombreux services Office 365, mais pas que. A chaque fois qu’on me posait une question dont je ne connaissais pas la réponse, ou qu’on me mettait le doute avec un “T’es sur hein” j’allais voir dans la doc officielle des produits et dans 80% des cas je pouvais répondre à n’importe quoi grâce à la documentation officiel.
- Maintenant je suis chez Axway, du côté Run pour notre application cloud, on est donc le seul à exploité cette solution et donc à la documenter. La documentation interne quand je suis arrivez était parfois ok, parfois mauvaise, parfois inexploitable, parfois absente ou même pas finis. J’ai donc deux expériences très différentes avec la documentation et de la est né ce talk
- Alors la première question qu’on peut se poser c’est écrire une documentation, vraiment c’est une compétence ? Eh bien oui, c’est même un ensemble de compétence qui sont : Savoir écrire en anglais de façon clair. Comprendre des technologie complexe Savoir les expliquer à l’écrit Et dans notre cas, très souvent comprendre aussi du code. Mais l’écriture de documentation technique n’est pas propre à l’informatique bien sûr.
- Mais genre vraiment y’a des gens qui sont payer pour écrire de la doc ? Alors oui on écrit tous un peu de doc à droite à gauche pour dépanner une collègue, mais oui ça peut être un vrai métier, d’après LinkedIn c’est surtout un métier au Etats-Unis quand même.
- Mais pourquoi c’est si important et surtout si c’est important pourquoi on n’a pas de cours de rédaction documentation à l’école ? Alors pour l’école je ne sais pas mais pourquoi avoir des compétences d’écriture technique est important c’est principalement car c’est l’outil le plus important pour transférer des connaissances facilement. Il a bcp de similitude avec le code, On passe plus de temps à lire de la doc qu’a l’écrire, on a tous des façons personnelles d’écrire et pour s’y retrouver il faut qu’on suivent les même et bonne pratiques, on peut faire de la doc review, du peer doc writting. Je vais même aller plus loin, la doc et le code sont tellement similaire que l’existence de clean code, implique l’existence de clean doc
- Alors on va voir quelques bonnes pratiques ensemble, les plus importante ou parlante, pour voir à quoi ça ressemble. La première est évidente, c’est d’expliquer des termes et au bon moment. Dans mon exemple je vous parle de SecureTransport, que vous ne connaissez pas, donc la définition suit. Par la même occasion j’introduis un acronyme que je vais pouvoir réutiliser dans le document maintenant qu’il a été expliqué. Par contre HTML je pense qu’il est inutile de vous l’expliquer, donc il ne l’est pas.
- Une documentation s’écrit aussi à la voix active, déjà car les phrase sont plus courte et c’est important. Ensuite ça rend les phrases plus claires pour celui qui doit faire les actions. Rappel de 5eme, la voix active c’est le chat mange la sourie, et la voix passive c’est la sourie est mangé par le chat. On peut aussi dire : La sourie est mangé et là on ne sait même pas par qui. En général on va utiliser des verbes a l’impératif pour ça.
- Le choix des mots est aussi important, encore une fois comme pour le code, une documentation va être lu, et relue, encore et encore. On préféra donc passer 2 minutes à trouver le bon mot qu’expédier ça en vitesse. On évite le verbe dit faible ou générique come occurs, happens, pour des verbes dit fort qui vont augmenter l’engagement du lecteur et surtout rendre le texte plus clair et moins répétitif.
- D’autre bonne pratique en vrac. On évite de changer le nom d’un composant en cours de route, on évite d’utiliser trop d’acronyme ou de pronom si ce n’est pas nécessaire. Enfin on tente de garder nos phrases les plus courte possible donc on enlève tous ce qui peut être superflu, adjectif, adverbe etc.
- Les listes et tableau sont aussi très important dans les documentations, c’est souvent la première chose que vous allez regarder et ils doivent suivre certaines règles. Déjà faite des listes dès que c’est possible, utiliser une phrase d’introduction. Et ayez des items parallèles, c’est à dire que visuellement on doit sentir que les items appartiennent à la même liste. C’est ici le cas avec ma liste en verte ou chaque item comment par une majuscule, termine par un point et a un rapport avec les autres items
- On évite les paragraphes trop longs qui sont intimidant (plus de 7 phrases en général), un bon paragraphe, répond aux questions suivantes : Quoi, Pourquoi, Comment. Il ne parle ni de ce qui se passe avant, ni de ce qui e passe après.
- Mais aussi on adapte notre document a notre audience, on n’hésite pas à définir les prérequis qui faut avoir pour lire ce document et si vraiment vous voulez être bon vous préciser le scope et le non-scope de votre documentation.
- Quelques mots sur les images. Un graphique trop complexe va effrayer vos lecteurs
- N’hésitez pas à faire plus simple si possible et de vous aider d’UML par exemple.
- Enfin on doit indiquer ce que le lecteur est sensé regarder ou voir sur l’image
- Maintenant, interrogation, si je vous dis : Texte pour intorduire une image Phrases courtes Mots simple 1 paragraphe – 1 sujet Listes Attention sur les pronoms Est-ce que vous pensez qu’on parle toujours d’écriture de documentation technique ?
- En faites non il existe le Facile à Lire et A Comprendre qui est un guide de bonne pratique pour permettre à des handicapés de lire et comprendre des textes et donc permettre une plus grande inclusivité. Quand j’ai découvert ça je me suis rendu compte que les règles du FALC sont en faites très similaire à ce qu’on devrait appliquer quand on écrit une documentation technique, mais aussi quand on communique par exemple avec des non-natif que ça soit francophone ou anglais d’ailleurs. Et rien que pour ça, je ne peux que vous encourager à améliorer vos compétences d’écriture technique, qui peuvent s’utiliser bien plus loin que le ReadMe
- Pour vous améliorer en rédaction technique je vous recommande d’aller lire les style guide Microsoft ou Google. Il existe un cours en ligne sur la rédaction technique fait par Google. C’est mon inspiration première. Aller réviser votre UML si nécessaire. Si vous voulez en savoir plus sur le FALC je vous conseille un article d’Anne-Sophie, et sur Twitter très probablement du contenue supplémentaire qui suivra sur ce sujet.