Technical writing: lessons learned from the attempt of writing a book chapter - Ioana Rosu - solarisBank

Attendees will learn that technical writing requires multiple skills, from an understanding of the technology to writing ability and social skills. It is not just about grasping technical information and recording it in a document. Technical writing takes high-level information and processes it into digestible content for a specific audience. Attendees might also be surprised to discover that the process can take just as much (or more!) time to plan and review than to write. All the knowledge is correlated with an attempt to write a book chapter.

Transcript

1. Technical writing lessons learned from the attempt of writing a book chapter
2. Who am I? • Ioana Rosu • Software Developer @ solarisBank • Twitter @alexanderspace_
3. How did I end up in this? • I am a regular human • I do sport, love programming and meerkats • I had some attempts to write short stories (fiction) ages ago • I received a proposal to write a chapter, part of a book about Go language
4. What came after it? PANIC!!!!
5. My Q&A • Who ever wrote a blog post? • What about a novel? • Who ever wrote a README? • What about a technical book?
6. The thing is… • Writing is a very big topic • Writing genres • Business emails, CVs, medical reports
7. Also… • Novels vs technical books • Free-writing vs accuracy • What did I learn from my project?
8. The roadmap for today • What is Technical Writing? • Style Definition & Benefits • The Technical Writing Process
9. What is Technical Writing? Is about processing information into digestible content with a specific meaning for a specific audience. Is not just about understanding technical information and recording it in a document.
10. Style Definition & Benefits • Clear, direct and neutral style • Guides the reader in how to use that information. • Becoming a little expert on that subject
11. The Technical Writing Process 1. Prewriting 2. Drafting 3. Revision 4. Editing 5. Publishing
12. Prewriting
13. Drafting
14. Revision, Editing, Publishing Are self explanatory
16. 1. Prewriting - The starting blocker
17. 1. Prewriting - facts • Document type • Goal • Consulting with experts • Audience analysis and understanding
18. 1. Prewriting • Gathering ideas • Planning • The outline
19. 2. Drafting - Writing in the correct style • Using the Active Voice Passive Voice Example: The electricity meter is read six times a year by a trained technician. Active Voice Example: A trained technician reads the meter six times a year. • Accurate Word Choice (less is more: details) • Avoid jargon
20. 2. Drafting - Consolidated explanation • The usage of examples • Visual display
21. 3.Revision • Revising content according to the outline • Checking for grammatical accuracy • Peer review
22. 4. Editing • Considering style and tone • Checking the intention
23. 5. Publication The unknown
24. What is the state of the story? • The chapter is in draft state • Still uncertain about one subtopic I would like to add • Still uncertain about the book situation regarding the publisher
25. Let’s recap • Writing is a process • Prewriting is the phase where a good part of the magic happens • Let’s not fall in the trap of the editor’s syndrome • It’s fun!
26. Writing is a journey, not a destination. Enjoy it!
27. Sources & credits • The big internet • Technical Writing A Guide for Effective Communication by Carmen Bombardó Solés Marta Aguilar … • Technical Blogging by Antonio Cangiano • Technical Writing: A Practical Guide for Engineers and Scientists by Phillip A. Laplante • Technical Writing For Dummies by Sheryl Lindsell-Roberts • https://www.publicationcoach.com/ Twitter @alexanderspace_
28. Q&A