Writing Great Documentation: What to write November 10th, 2009
Tech docs can take a bunch of different forms ranging from high-level overviews, to step-by-step walkthroughs, to auto-generated API documentation. Unfortunately, no single format works for all users; there’s huge differences in the way that people learn, so a well-documented project needs to provide many different forms of documentation. At a high level, you can break down the different types of documentation you need to provide into three different formats:…
Writing Great Documentation: Technical style November 11th, 2009
Now that I’ve discussed what kinds of technical documentation to write, I can move on to the question of how to actually develop a writing style that produces great technical documentation. Learn to write Unfortunately, there aren’t any shortcuts here. The best way to learn how to write great documentation is to first learn how to write (anything). There are some important differences between technical documentation and your average prose, but a solid foundation of good written communication skills is an irreplaceable prerequisite.…
Writing Great Documentation: You need an editor November 12th, 2009
I’m supposed to be this expert on writing, right? So how come my previous articles have had so many errors? Simple: my blog doesn’t have an editor. That’s typical for a blog, but it’s unfortunately also typical of open source documentation: the vast majority of technical documentation doesn’t reach far beyond rough draft status. All good writers have a dirty little secret: they’re not really that good at writing. Their editors just make it seem that way.…
Coworking With a Friend to Write More March 9th, 2021
In early January, Sumana Harihareswara and I started getting together a few times a week to help each other write more. This model of working together on separate-but-related projects has worked really well for us, and we wanted to share our model and our details to encourage other folks to give it a shot.
🔗 Becoming a Better Writer in Tech January 19th, 2022
Great advice on getting better at writing.
Writing With Copilot October 14th, 2022
On using Copilot as a writing assistant, and my complex feelings about the ethics of doing so.