19/12/2014
(Too Long, You’ve Bored Me)
If you’re a tech writer, you reaaaaaally need to read these: Microsoft Manual of Style, The Elements of Style, The Innovator’s Dilemma, and How Google Works.
If you’ve read any of my posts, you’ve understood that I’m pragmatic.
I believe in creating great products. Somewhere along the way you need to make compromises, and that’s when you need documentation.
There is only one thing I really think needs to be documented - APIs. But that’s another post for another time.
Most times as a tech writer you’ll be outnumbered by the developers around you. At OutSystems there’s one of us for 10 developers. So if you want to help create great products, you’ll need some other skills other than writing. Otherwise you’ll be overwhelmed by the amount of work that keeps pilling up, as the development teams keep shipping.
In this post I’ll focus on books that cover four skills I think you need to improve every day to keep up the pace:
This is a pragmatic reading list, so I’m not telling you to read these books from start to finish. You should scan them first and only read the parts that make sense to you. You can always use the books later as a reference, when you are in need of inspiration.
I could have included many more books on the list. I believe these have very interesting ideas, and I hope they challenge your convictions. The hard things to learn are the ones we don’t even know existed. I call this meta-ignorance, but you might also know it as the “unknown unknowns”. And I believe the books in this list have the power from turning you from meta-ignorant to ignorant, just like they did with me. They'll let you thinking about stuff that you won’t know if is important or not. And they’ll send you in the right direction if you want to search for more.
Ufff… after a long introduction, let’s jump to the books:
This is a long book, so I suggest that you skim the pages just to get a general overview of the content. And then you can use it as a reference, when you need it. For example, if you find yourself having long discussions about the Oxford comma, just find what this book tells about it.
Here are some chapters I find valuable.
This chapter is all about Windows terminology. Nonetheless, it might make sense to read it, to see how Microsoft has thought out the terms they use in the UI and the command line. It also has some generic advices on writing clearly and unambiguously.
This chapter covers how to present headings, cross-references, lists, tables, and what not. It's all about consistency. If you have a huge team creating docs or a huge product, this is for you. With a huge team it’ll be difficult for everyone to know the conventions. So reading this chapter offers some insights on how to come up with good ones.
If you deliver content for a global audience (who doesn’t these days?) this chapter is for you. It basically tells you how to use examples, images, colors, and other stuff that won't offend anyone around the globe.
I usually pay attention to creating great sample data and great stories that my readers can identify with. But if you take internationalization to the limit, I think your documentation will be a bit soulless and dry. So the key is trying to balance both and try to offend no one in the process.
Again, this chapter has some great example on how to write clearly, but those examples are dispersed throughout the chapter. This is a bit unfortunate, since you’ll have to read the chapter to get to the examples.
This chapter has great advices for both developers and documentarians. It mostly covers how to create reference documentation, code comments, and coding style. Yes, this is mostly what Microsoft advocates and practices. But if you abstract from that I think they provide great advice which you can use in whatever platform you develop for.
Even if you don’t read the rest of this book, be sure to read this part.
This chapter discusses the writing tone. Being Microsoft their style guide tends to be a bit dry, but that’s OK. You’ll get a sense about what you should think about to ensure you have a consistent tone across your products and docs.
This one covers some common formatting problems. It covers dates, numbers, phone numbers among other stuff. It’s a good chapter to use as reference for creating great sample data that everyone around to world can understand.
This chapter offers some great examples on using the grammatical elements. The Elements of Style is a great book but I fell it falls short on the number of examples it has. This chapter is a good complement.
This one offers advice and examples on using periods, commas, colons, etc. Again, a good complement to the Elements of Style.
This book offers great and actionable advice on how to write. It also adds the cherry on top of the cake by having great examples. The book is basically divided into three or four parts.
Rules of usage that you should follow, how to translate ideas into sentences and paragraphs. It also covers formatting (like using headings and numerals), and commonly misused words.
Here’s some great lessons I took from this book:
Even though it has around 400 pages, the book is well organized. The introduction explains how innovations comes to be and how small innovative companies can defeat incumbents.
The main thesis of the book is that the same factors that make incumbents successful, are the ones that can drive them out of business. The rest of the book explains what these factors are.
And the book offers great case studies to illustrate the point. One of the examples is the disk drive industry from the 80's to the 2000's. During this period lots of companies were founded, became incumbents, and eventually went out of business.
This is one of those books that changes the way you look at the world. You’ll soon start to think about the world in the light of this thesis. It will also show you why you should’t pay too much attention to those companies that make reports about industry trends.
If this sounds interesting to you, go read it!
Most often than not, technical writing teams need to move fast to keep the pace of the dev teams. It means that everyone on a tech writing team should be autonomous and a leader. That way they’ll move fast to compensate where they are needed, and without much friction.
This book was written by Eric Smith, Google’s CEO from 2001 to 2011. I can’t do justice to the book, but here’s the summary of some lessons that struck me the most.
Most often than not the best ideas get few consensus at the beginning. It’s not because they are controversial, but because great ideas come from technological insights. And only a handful of people master a given technology at a time, so it’s difficult for others to see the value of the idea.
Nonetheless, the right decision is the best decision. It’s not a compromised version of the original idea, that has been distorted to achieve consensus. So the best thing to do, after finding an idea is:
When you detect a crisis (in a tech writing team this means almost every week), do like fighter pilots. Instead of reacting by impulse, first assess the situation and act with all the information you can gather.
Our first instinct is to do something, but reacting without information will only cost you time. But there's a point were you'll need to act.
If you are hiring well, you’ll be surrounded by smart creatives. Smart creatives are not compelled by rank or by someone screaming at them. To take the most out of them you'll need to give them ultimate goals, and let them work to achieve those goals. Make sure you set deadlines to make arguments more efficient.
Even if you think you are right, and want smart creatives to do what you think is best, you'll need to win their hearts with real data.
Just like projects, meetings should have a single owner. The owner should be responsible for:
Everyone should feel free to skip or leave a meeting if it's not productive. And yes, everyone on the meeting should be focused 100% on it. If people are multi-tasking on your meetings, find ways to make them more productive.
You (and everyone) are responsible for sustaining a mentorship culture. You don’t need to be an expert to be a mentor and provide valuable insight. Most professional athletes have coaches that suck at playing the sport, but can provide insights on how a player can improve.
You want to surround yourself with smart creatives due to their ability to think, not only because they can execute. So you should be able to clearly communicate the goals, but let them decide the best course of action to get there.
If you are a manager, your goal is to ensure information can flow easily through the company. Yup, essentially you should be like a router.
You also need to make sure your smart creatives can tell you the truth no matter what it costs you to hear it. If the people surrounding you won’t tell you the truth, you’ll not be able to mitigate the risks and steer the team in the right direction.
One-on-ones are a way for your team to provide and be provided with honest feedback in private. You and the team member should bring a top five list of issues that deserve attention to the meeting. Then you cross-check the lists and address the common issues.
You can also use the following agenda: - Performance on job; - Relations with peers; - Leadership and mentorship; - Innovation and best practices.
You and everyone around you should be seeking ways to produce and implement novel and useful ideas. They should deliver value in a way that your current customers did not even thought about.
Don’t try to create a hierarchy to develop innovation within your company. Innovation comes from below, so if you create the right conditions it will thrive.
You just need to set goals high, and let smart creatives strive to reach the goals.
After you ship a product, you should continue to iterate on them. But you also need to pay attention if it is getting momentum or not. Products with momentum should have more resources allocated than products with few.
This ensures that even if you fail, it won’t cost you much, and will be easy to reallocate the resources to other projects.
I would love to see what books are on your reading list. Shoot me a tweet or email and let me know.