If you're a good writer, it's pretty straightforward to learn to be a good *technical* writer. What separates the great ones from the good ones isn't writing ability; it's the additional?focus?on 3 elements:?collaboration,?user experience, and socialization.?
Collaboration is critical. Good technical writers write good docs on topics they're SMEs about, but great ones partner effectively with others to leverage?their?knowledge to write excellent documentation. Here are some best practices to make your collaborative efforts more effective.?
- Come prepared?- Come with good questions; make excellent use of SME's time. Do your homework in advance to let them know you're responsible and have done your due diligence to make the best use of their time by not asking them to review the basics.?
- Polish your drafts to your reviewer's expectations??- Understand how thorough the draft/revision should be, based on your collaborator's?preferences and the timeframe.?Don't be afraid to explicitly ask them: do they want to wait for a near-final version, or do they want to see the messy WIP?
- Make your?SMEs look good?- If there's a SME helping you, make sure they get credit for their work–it's their knowledge that's on display!?Shout them out publicly, email their boss praising them for their help, etc. Create positive experiences collaborating with TW, to make it that much easier to convince someone to partner in the future.
- Close the loop?- Show results to your SMEs, validate their involvement, show the impact. Makes it easier to maintain.?
Good user experience is part of being a good technical writer, but the excellent ones focus on the macro UX—the whole context their?reader is in—not just the micro situation.??
- Focus on the macro?-?Do the work to understand where your audience is coming from AND where they're going (this is easy to skip). This might mean doing quite a bit of?extra?work to improve the information flow a doc is part of, or to reorganize the IA of a training (or a whole program). This probably won't be in your job description, so you'll need to use "influence without authority" skills to make progress here.?
- Take responsibility for your?readers' understanding?-?If they don't get it, it's your fault. Take this as inspiration to improve your docs and better understand your user.?
- Take design seriously?- Taking responsibility for your user's understanding goes beyond words; the way a doc?looks?is nearly as important as the content within it. Design, graphics, and information design are all part of the repertoire here, despite probably not being on your job description.?
Writing docs is one thing; that's what you were hired to do. But you don't (or you shouldn't) get any points for docs that aren't actually?read?and?used. Great technical writers take it upon themselves to make sure their docs are actually used by–not just theoretically useful to–their?intended audience.?
- Spend time telling people what you did?– Evangelization isn't often a natural gift of technical writers, but you've got to tell people about the doc before it'll get used. It's easy to think "if we write it, they will come"–but that's not reality. People are busy, and habits are hard to break. You've got to show them what you've done, sometimes multiple times, before it'll stick.?Doing this well means avoiding duplication of information, an easier time recruiting SMEs in the future, and kudos for you and your team.?
- Plan for maintenance?-?A lot of docs get written, then forgotten, then go stale.??If you've done a good job with socialization you'll have built-in mechanisms for feedback to let you know when it gets stale, but regardless: plan for future maintenance.
- "Programmize" everything?-?If no one else is doing this, it's your job.?Use your docs to create structure where there is none, using all these techniques: collaboration, user experience, and socialization.
Technical Writer
3 年yah that Joseph Barsness is a keeper all right :-)