Docs by Design
1,108 FOLLOWERS
Bob Watson ponders technical writing, API documentation, and the world in general.
Docs by Design
1M ago
I review some examples of my earliest technical writing to see into the future.
I'm afraid that, the more things change, the more they stay the same.
The post A look at the past to see the future of technical writing first appeared on Docs by Design ..read more
Docs by Design
2y ago
In my previous post, I presented some experiences with testing and the resulting epiphanies. In this post, I talk more about the process I applied. The process is simple, yet that’s what makes it difficult. The key to success is to take it slow. The question Start with something simple (and then simplify it). Your ..read more
Docs by Design
2y ago
Less is more is a mantra frequently heard in technical writing. When applied to editing, this works out to be something like, “After writing, keep taking the words out until it stops making sense, then put the last word back in.” While this approach applies to technical writing in general, it comes into sharp focus ..read more
Docs by Design
2y ago
Wikipedia says that the curse of knowledge “is a cognitive bias that occurs when an individual, who is communicating with other individuals, assumes that they have the background knowledge to understand.” I’ve suffered that curse on various occasions, but I think I might have a way to reduce its frequency. Know your audience. Thank you ..read more
Docs by Design
2y ago
In my previous post, If it’s not statistically significant, is it useful? (and every grad-school class I taught statistics), I talked about staying within the limits of your data. By that, I mean not making statements that misrepresent what the data can support—basically, keeping it real. Correlation is not causation Perhaps the most common example ..read more
Docs by Design
2y ago
In my last post, I talked about How you can make sense of your site analytics. But once you make sense of them, what can you do with them? Let’s say that you’ve applied that method and you can now tell the information from the noise, what’s next? The goal of the method presented in ..read more
Docs by Design
2y ago
Looking through some classic examples of technical writing, I noticed how the format of API reference topics hasn’t really changed in the past 30 years. So where does TC need to innovate ..read more
Docs by Design
2y ago
In most technical writer interviews I've had, I've been asked, "Did you read our docs," which they invariably follow with, "What did you think of them?" How should you answer? Here's what I've learned, the hard way ..read more
Docs by Design
2y ago
Today I met with my co-jurors who’ll be judging this year’s DevPortal awards nominees with me in the coming weeks. The entrants in this year’s showcase represent an impressive effort on the part of the nominees, so we have our work cut out for us. This is my third year on the jury and I’m ..read more
Docs by Design
2y ago
Some time ago, I was a filmmaker. Honestly, I wasn’t especially good at it. I wasn’t bad, just OK. However, while I enjoyed the work, using my checkbook balance as a metric, I wasn’t good enough at it to make a living. Because of that, I’m a technical writer. Filmmaking, however, taught me a lot ..read more