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

Slide 1

Slide 1 text

Technical writing lessons learned from the attempt of writing a book chapter

Slide 2

Slide 2 text

Who am I? • Ioana Rosu • Software Developer @ solarisBank • Twitter @alexanderspace_

Slide 3

Slide 3 text

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 (ﬁction) ages ago • I received a proposal to write a chapter, part of a book about Go language

Slide 4

Slide 4 text

What came after it? PANIC!!!!

Slide 5

Slide 5 text

My Q&A • Who ever wrote a blog post? • What about a novel? • Who ever wrote a README? • What about a technical book?

Slide 6

Slide 6 text

The thing is… • Writing is a very big topic • Writing genres • Business emails, CVs, medical reports

Slide 7

Slide 7 text

Also… • Novels vs technical books • Free-writing vs accuracy • What did I learn from my project?

Slide 8

Slide 8 text

The roadmap for today • What is Technical Writing? • Style Deﬁnition & Beneﬁts • The Technical Writing Process

Slide 9

Slide 9 text

What is Technical Writing? Is about processing information into digestible content with a speciﬁc meaning for a speciﬁc audience. Is not just about understanding technical information and recording it in a document.

Slide 10

Slide 10 text

Style Deﬁnition & Beneﬁts • Clear, direct and neutral style • Guides the reader in how to use that information. • Becoming a little expert on that subject

Slide 11

Slide 11 text

The Technical Writing Process 1. Prewriting 2. Drafting 3. Revision 4. Editing 5. Publishing

Slide 12

Slide 12 text

Prewriting

Slide 13

Slide 13 text

Drafting

Slide 14

Slide 14 text

Revision, Editing, Publishing Are self explanatory

Slide 15

Slide 15 text

No content

Slide 16

Slide 16 text

1. Prewriting - The starting blocker

Slide 17

Slide 17 text

1. Prewriting - facts • Document type • Goal • Consulting with experts • Audience analysis and understanding

Slide 18

Slide 18 text

1. Prewriting • Gathering ideas • Planning • The outline

Slide 19

Slide 19 text

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

Slide 20

Slide 20 text

2. Drafting - Consolidated explanation • The usage of examples • Visual display

Slide 21

Slide 21 text

3.Revision • Revising content according to the outline • Checking for grammatical accuracy • Peer review

Slide 22

Slide 22 text

4. Editing • Considering style and tone • Checking the intention

Slide 23

Slide 23 text

5. Publication The unknown

Slide 24

Slide 24 text

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

Slide 25

Slide 25 text

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!

Slide 26

Slide 26 text

Writing is a journey, not a destination. Enjoy it!

Slide 27

Slide 27 text

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_

Slide 28

Slide 28 text

Q&A