Writing and Editing Technical Documents

Transcript

1. WRITING AND EDITING TECHNICAL DOCUMENTS
2. Victor_Codejs Victor Ikechukwu Frontend Developer Technical writer @ Freecodecamp, ContentLab, Draft.dev, Hashnode, and more... DevRel Ambassador @ Storyblok Wannabe Fashion Model I code and talk/write about code Meet Victor Ikechukwu
3. Victor_Codejs Victor Ikechukwu Session outline Principles of Effective Technical Writing Techniques for Writing Clear and Concise Technical Documents Technical Writing Style Guides 1. 2. 3.
4. Victor_Codejs Victor Ikechukwu Principles of Effective Technical Writing
5. Victor_Codejs Victor Ikechukwu Understand the purpose and audience of your technical documents: To create effective content, you need to identify "who" you are writing for, and "why".
6. Victor_Codejs Victor Ikechukwu Prioritize clarity, precision, and conciseness: Comedy writers seek the funniest results, horror writers strive for the scariest, and technical writers aim for the clearest and most concise.
7. Victor_Codejs Victor Ikechukwu In accordance to/with → Following In order to → To On a daily basis → Daily Return back → Return - Introduce the value proposition of the content early: Clearly state what the reader will get out of reading your article. Preferably within the first two paragraphs. - Eliminate repetition and redundancies (DRY): Read each sentence and ask yourself if it introduces new information, ideas, or analysis. If it is simply restating old information, rewrite it or delete it. - Cut out unnecessary prepositions and adjectives: Your sentences would still convey exact meaning without them
8. Victor_Codejs Victor Ikechukwu Organize information logically and effectively: Structure the layout of your technical documents in ways that promotes readability, and is easily skimmable.
9. Victor_Codejs Victor Ikechukwu Group your writing into sections that emphasize just one key point or idea Use clear & descriptive subheaders that concisely reflect the subject of a section. (Also helps w/ SEO) Include a table of contents, if applicable, so readers can easily navigate to the areas that are most relevant to them. Break up sequential items into lists Break down long sentences and paragraphs into smaller bits (Let your content and readers' eyes breefff 😮‍💨, don't suffocate them. You have that responsibility)
10. Victor_Codejs Victor Ikechukwu Techniques for Writing Clear and Concise Technical Documents
11. Victor_Codejs Victor Ikechukwu Use plain language and avoid jargon: If your readers wanted to improve their vocabulary, they would have probably used that time to read the latest edition of the Oxford dictionary. (Again, let your readers' breefff 🙏🏼 )
12. Victor_Codejs Victor Ikechukwu Structure sentences and paragraphs for readability: Break up your text into paragraphs of 2 - 3 sentences max, where each sentence expresses a single thought. Not doing this will create paragraphs or, rather, walls of text that are too long and hard to read.
13. Victor_Codejs Victor Ikechukwu Before ❌ After ✅
14. Victor_Codejs Victor Ikechukwu A Look at Technical Writing Style Guides
15. Victor_Codejs Victor Ikechukwu A style guide helps you write clearly and consistently across all your documents. A style guide is like a map. It helps turn a thousand thoughts and ideas into a cohesive structure. It ensures that your technical documents deliver on their intended purpose, getting the reader from start to finish.
16. Victor_Codejs Victor Ikechukwu Common elements of a technical writing style guide: Voice: The tone you should use to engage readers and establish a clear point of view. Formatting Naming convention Writing Guidelines
17. Victor_Codejs Victor Ikechukwu Implementing style guidelines in your writing: The Draft.dev Technical Blogging Style Guide GitLab Documentation Style Guide Google Developer Documentation Style Guide Now that you know what style guides are and their importance, you can try your hands at the style guides below and implement them in your own writing:
18. Victor_Codejs Victor Ikechukwu Summary
19. Victor_Codejs Victor Ikechukwu Thank Youuu
20. Victor_Codejs Victor Ikechukwu Q & A
21. Hello!! And welcome to day 2
22. Victor_Codejs Victor Ikechukwu Recap from yesterday: Define your target audience early on Prioritize being clear and concise in your writing Structure technical documents in ways that lets your readers breefff 😮‍💨 Use plain language and avoid jargon As you advance, consider adopting a style guide to improve consistency 1. 2. 3. 4. 5.
23. Victor_Codejs Victor Ikechukwu Session outline Avoiding Common Mistakes in Technical Writing Reviewing and Editing Technical Documents for Accuracy and Clarity Incorporating Graphics, Tables, and Diagrams in Technical Documents 1. 2. 3.
24. Victor_Codejs Victor Ikechukwu Avoiding Common Mistakes in Technical Writing
25. Victor_Codejs Victor Ikechukwu Grammar and punctuation errors: It's the little things that matter, and when a lot of things are wrong, no matter how little they are. It becomes a big thing.
26. Victor_Codejs Victor Ikechukwu Reviewing and Editing Technical Documents for Accuracy and Clarity
27. Victor_Codejs Victor Ikechukwu Editing (verb) /ˈɛdɪtɪng/ The process of preparing (a material) for publication by correcting, condensing, or otherwise modifying it. Proofreading (verb) /ˈpruːfˌriː.dɪŋ/ The process of finding and correcting mistakes in the text before it is printed or put online:
28. Victor_Codejs Victor Ikechukwu Importance of proofreading and editing: Editing and proofreading are the interior designing of a building. The process can take the most basic piece of writing and enhance it to become the best version of itself.
29. Victor_Codejs Victor Ikechukwu However, as vital as editors are, you may not always have access to them for various reasons. In such situations, self-editing becomes an invaluable skill.
30. Victor_Codejs Victor Ikechukwu Techniques for effective self-editing
31. Victor_Codejs Victor Ikechukwu Step away for a bit: If you can afford the luxury of time, put some distance between your draft and when you start editing.
32. Victor_Codejs Victor Ikechukwu Understand that nothing is perfect: As Leonardo da Vinci said: "Art is never finished but abandoned". Set a deadline and an acceptable number of edits (say, 2), stick to it, and consider it done.
33. Victor_Codejs Victor Ikechukwu Don't do it alone, utilize tools: Grammarly Quilbot Hemingway App WordTune ChatGPT
34. Victor_Codejs Victor Ikechukwu Seek feedback and incorporate revisions: If writing for yourself, you can either stop at the self-editing stage and move on to publishing, or ask for feedback from an extra pair of eyes (like a friend, colleague, etc). However, if you're writing in a professional setting, you'd usually need to send your draft to your clients or superiors for feedback and then try to incorporate their suggestions.
35. Victor_Codejs Victor Ikechukwu Incorporating Graphics, Tables, and Diagrams in Technical Documents
36. Victor_Codejs Victor Ikechukwu Choose appropriate visuals to enhance understanding: A picture conveys more information than a thousands words
37. Victor_Codejs Victor Ikechukwu Creating clear and effective graphics, tables, and diagrams: Canva Figma Adobe
38. Victor_Codejs Victor Ikechukwu Integrating visuals with text seamlessly: Use captions (and alt texts if possible) Clearly describe what's in the diagram either in the paragraph above or under it. Cite their sources (plagiarism)
39. Victor_Codejs Victor Ikechukwu Assignment
40. Write a technical document based on the outline that you created in week 2 Apply the principles, techniques, and concepts shared throughout both sessions on how to write and edit technical documents Victor_Codejs Victor Ikechukwu
41. Practice the techniques covered in theses sessions and seek feedback from peers or mentors. Victor_Codejs Victor Ikechukwu
42. Victor_Codejs Victor Ikechukwu Q & A
43. Victor_Codejs Victor Ikechukwu Thank Youuu