Modern technical writing, a talk by Andrew Etter about his book
Yesterday I attended a Write the Docs meetup where Andrew Etter spoke about his recently published book, Modern Technical Writing: An Introduction to Software Documentation.
I haven’t read Andrew’s book yet, so I appreciated this introduction from the author. One thing that strikes me is how interwoven are two aspects of technical writing: firstly, the processes (the way we glean our material and our efficiency and efficacy in writing content); secondly, the tools we use. Every now and then, I’ve heard people say we shouldn’t focus so much on the tools when discussing our profession and how best to perform our role. I’ve thought that too, at times. But it seems to me that these two aspects of our work are becoming more and more interdependent. The tools make a specific way of working possible, and the way we think of our work determines the tools we choose.
From what Andrew said about his book yesterday, the content of the book seems to agree with my above musings. Now, I should go and read that book. 🙂
Modern Technical Writing, the book
Andrew pointed out that you can read his book in about 45 minutes, and that he’s been allotted an hour for this talk! This comment raised a good laugh.
The book is about 11,000 words. Andrew summed it up (with a smile) in about 12 words, which roughly correspond to the highlighted words in the list below:
- Learn – learn your subject matter and get to know your audience.
- Write in lightweight markup – it’s the easiest way to get from a pleasant writing experience to a useful website. Markdown is a good solution, because people want to use it. You’ll therefore have plenty of people willing to contribute to your docs.
- Treat the docs as code – version control and continuous updates. The stability of the docs over time depends on the quality of your updates.
- Create static websites.
The book, Modern Technical Writing, started as a wiki page. Andrew needed information about technical writing to pass on to others. He did a bit of research, to see if anything already existed that he could use. Having found nothing that fit the bill, he decided “I’m the writer”, and wrote it himself.
What makes a book sell?
Andrew spoke amusingly about an FAQ on the Kindle Direct Publishing site: “Why am I not selling? I am a good writer.” The fundamental question is, how do you get people to buy something you’re selling? Andrew said with a smile that he has no idea! He doesn’t do much marketing or promotion via social media. Here’s his recommendation:
If you have something you feel strongly about, something you’ve shown to your friends and got good feedback on, something you think adds value to the world, then put it out there.
The publishing process
Andrew chose Kindle Direct Publishing as the mechanism for publishing and earning royalties. The rules around pricing are really complicated. The magic happens when you upload your book to Amazon, and they transform it to a Kindle book. Amazon is the market leader in online publication, and your book benefits from this.
One drawback is that you cannot test your book before publication. You just upload it, view the highly inaccurate preview, and then publish it.
Andrew showed us a screenshot of his book on Amazon right next to Strunk and White’s Elements of Style. To be near Elements of Style is mind-boggling. But it lasted a very short time. He dispelled any myths that self-publishing is lucrative. He has, however, received very nice messages from people all over the world.
Charging a price for the book
If you give something away for free, there’s the perception that it’s not really valuable. If you give it a price, people are more likely to see it as worth something.
For his book, Andrew thinks that the price of around $4 is in the right range.
What technical writers do
What is the “differentiated value add” of a technical writer? That is, what do we do that no-one else does?
- Consistency – specifically, consistency in tooling. Without tech writers, each engineering team would pick their own tools, which would result in chaos.
- Accountability – someone has to be responsible for creating good documentation. Andrew remarked with a smile that you have to be able to fire someone if the documentation is bad.
- Creation and curation – writers review and take care of others’ content as well as writing it.
- Culture – having good writers around makes everyone else aware of what good writing looks like.
- Good documentation leads to efficiency improvements in many ways. It helps the organisation and customers save time, and time is a precious resource.
Andrew talked a bit about the writing process, project prioritisation, and the team. He joked at the beginning of the presentation that these topics may form part of the second edition of the book, if he ever considers writing one.
The old way versus the new way of producing documentation
Andrew talked about old methodologies and tools versus the new ones, and walked through some code samples. I didn’t make notes of this part of the talk. The details are in Andrew’s book.
Thanks to Andrew Etter for an engaging presentation and congrats on your successful book!
Posted on 19 November 2016, in technical writing, Write the Docs and tagged technical communication, technical documentation, technical writing, Write the Docs. Bookmark the permalink. 3 Comments.
Thanks a lot for this interesting review Sarah. I’ve been following you since the days you were working on Confluence.
As you mention tools, I would be very interested in understanding what tools you’re using on a daily basis. I’m using Word and Confluence, for different purposes. I’ve always found Word was not the perfect solution but I’ve never been able to find a better tool. I don’t say there’s nothing better, it’s just that I don’t know a better tool, it’s a matter of knowledge on my side. Also, when it’s time to delivering documentation we rarely think about what to use, we go straight to Word. What would you recommend?
And thanks again for your very interesting blog.
Hallo Lionel, Interesting questions! I think the choice of tool depends very much on your requirements – audience, contributors, and environmental resources. I’m currently working on API documentation. The contributors to the docs include software engineers, support engineers, product managers and others, as well as the technical writers. For us, it makes sense to keep the doc tooling as close as possible to the software code. We write in HTML and Markdown, with Django for content reuse and templating. The doc source lives in the same repository as the software code, which we access using a custom version of Perforce and Git. We have a custom publication engine that pulls the source from the repo and converts it to web pages. All in all, it’s fun and works well. There’s the occasional hiccup or frustration, but that’s so with most systems.
It’s nice to hear from you!
Pingback: Book Review. Modern Technical Writing: An Introduction to Software Documentation, by Andrew Etter, 2 of 3