I've been having trouble getting started on this blog. There are a lot of things I'd like to talk about here... developer support, API usability, managing a team of writers, and, of course, documentation. The problem is that I haven't been able to figure out what to talk about first.
It just struck me that the reason for dragging my feet is that I haven't thought about who my audience is.
When you start a new tech writing project, the first thing you do is figure out your audience. Then you figure out what they're trying to do. Once you know your audience's starting point, and figure out where they're trying to go, you can figure out what you need to do to help them get there.
The challenge with blogs, and with public web documentation in general, is that absolutely anyone can read what you're writing. If you're reading this right now, you could be a fellow tech writer (either just getting started in your career, or a veteran), a developer, or a tech writing manager. And those are just the basics. Heck, you could be a fly fisherman who stumbled across this page accidentally (and is probably wondering why he's still here.)
Web docs have similar challenges, especially those for APIs that are offered freely to the general public. One developer might be a student, who is trying to piece together an app over cold pizza at 3am because he saw an interesting article about the technology on Slashdot. Another developer might be writing an enterprise app as part of her day job. A third developer might be working on an cutting-edge application for that startup he always dreamed about creating.
One developer might create web apps every day, and know everything that's out there about it. Someone else might be used to writing drivers in C, but have zero experience with Java. And yet another person might have no development experience whatsoever; they're trying to get something working by copy-and-pasting sample code and hoping for the best.
How do you write one document that works for everyone?
Believe it or not, it is possible, depending on your definition of "write one document." You can't do it if you expect all of your readers to sit down and read a thousand-page manual from start to finish. But if you use good navigation and information architecture, and well-configured search, then anyone can find what they need.
The navigation of your docs should work for as many of your typical developers as possible. People should be able to quickly find the docs that explain what they're trying to do, without having to read through a lot of irrelevant prose. As a writer, you should think about how to reuse information intelligently. For example, everyone will need to authenticate their app, so the docs that explain authentication should be linked from lots of places. On the other hand, only certain apps will need to use particular sequences of methods.
The web is a goldmine of information. There's no need to explain the basics, such as how REST works. Find a good resource that explains it, and link to that resource.
But most importantly, just take the time to think about who your audience is. Being cognizant of who is reading will help guide what you write, even if you just tuck that knowledge away in your subconscious and don't do anything about it.
So back to this blog. If you're new to tech writing, or new to tech writing management, I hope this blog is helpful to you. Please feel free to email me with questions and topic requests. I'll link to additional helpful resources as I find them. If you're an old pro, or a developer, let's get a conversation going. Please jump in and argue my points, if you're so inclined! Regardless of who you are, you can navigate the blog by topic or by search.
No comments:
Post a Comment