As a new Technical Writer, I would always think things like, “No one will review my doc!” and “My docs are wrong now because dev changed the UI without telling me!” or “I can’t possibly finish everything I said I’d do by Friday.” or “I guess I shouldn’t have sent that email.” Sometimes, our best laid plans fall apart, people let us down, requirements change, — you know these things that happen everyday on the job! Snafus might be everyday occurrences, but they can really discourage a new Tech Writer.
Here are some sticky situations that I have been in and my reflections (of course, hindsight is 20/20)
- I was once the only Tech Writer in the whole company. So, I became the point of contact for all incoming requests for internal documentation (e.g., assembly procedures, inter-departmental forms, etc.), and was losing track of those requests amid my other “normal” customer-facing document responsibilities.
💡 Write down each task when anyone “stops by” with a request. Capture all the information about the content, audience and deadlines. Now you will have a prioritized list of requests.
- I spent a lot of time and effort repeatedly updating and releasing a manual that was supplied printed in the box with the product (to keep it up to date with software changes). It wasn’t until the end of the year that I discovered the print runs of the manual were so large that not even my first revision had yet left the building!
💡 I learnt then that it’s important to know how the documentation is delivered to the user. A tech writer should ideally be involved in the documentation process end-to-end — and the other end is the end-user.
- I started writing the docs based on the design specifications. My developers told me it would be too much trouble to set up a prototype system for me to work with. At the last-minute I realized that the finished product didn’t match the design spec. Oops!
💡 Always insist on getting that prototype. You should not wait until the last-minute to verify the design specs with the developer.
- The docs looked great in my authoring tool, and when I saved to PDF. Then, I was asked to provide an HTML version for the website. Oops, it didn’t look so great.
💡 Relying on one particular authoring tool is the easy way out. But when choosing a tool for documentation across different formats, tech writers should be careful in choosing a tool that caters to all. We should be clear about what output formats would be required and then develop the docs in a way that would support them.
- I started working on a project that did not a have a clearly defined “finish line”. There was a never-ending series of “oh, just one more small change” requests. I had to constantly work on the documentation changes, which took out a huge chunk out of my time.
💡 A skill that’s needed, technical writing or otherwise, is effectively managing so-called “scope creep”. One way to shut that down is to draw a firm line between what’s needed for the current version and what will be part of the next version. It is essential to have the required “soft skills” in your arsenal to negotiate in these kind of situations
- In my first job, Technical writing wasn’t included early enough in the development process, so I ended up being rushed to complete work that would have been no big deal if we’d been able to start earlier.
💡 Sitting in on recurring design review and product management meetings helps a lot. You need to be able to squeeze yourself into these gatherings and remind the others in the office that they actually have a Tech writer. Combing through long CC: email threads and network file folders for evidence of projects I might need to go stick my nose into was a useful trick as well.
You should be mindful of the perils of installing upgrades to authoring tools before a deliverable. You need to set up a separate test environment for these upgrades and spend the time to create a full test plan to verify that the documentation is output as expected. This might seem obvious, but I’ve been through too many software upgrades that seem to work fine at first glance only to discover insidious problems with formatting, broken links, image display, and more.
We learn through trial and error what to do, when to start, and whom to go to. And of course, some things just keep happening because no matter what we try, projects never go quite as expected.
What examples come to your mind? Are there any snafus that you’d like to warn & advise new tech writers about? Share your stories in the comments!
Want to be more productive as a Tech Writer? Read my previous post! 🤓
The New Technical Writer 