Working with a freelance or contract technical writer: the user guide

“How can we set this project up for success?”

As a freelance technical writer, I love it when a client asks me this question. It’s a great sign that they appreciate the value that user-facing content can provide, and they want to get the most out of our collaboration. It means they don’t see documentation merely as a tick box exercise, but as a way to support and streamline the entire customer experience.

Having worked on both a contract and freelance basis with organisations of various shapes and sizes over the years, I’ve found three key areas that can make or break a technical writing project.

Avoid skunkworks

Hiring a freelancer or a contractor means you’re engaging someone from outside your organisation. There are several reasons you might go down this route. Perhaps you’ve never had a technical writer on staff before and want to start with a short-term engagement. Perhaps you don’t have enough work to justify employing a full-time writer. Or perhaps you see the value in having a complete outsider come into your development process and look at your product or service with a fresh pair of eyes.

Whatever the reason, if you’re engaging an external writer, make sure you discuss the decision with those involved in developing or supporting your software. Don’t rely on them catching on by osmosis or leave it to us to tell your employees about the project. Without an introduction and the blessing of someone in authority, teams are unlikely to share the internal wiki pages, Slack channels and other resources that help a technical writer really get to grips with the details of your software.

Furthermore, if members of your team haven’t worked with a writer before, they may have preconceived ideas about how writers should work and what we should (and should not) contribute. How you introduce the role will impact individuals’ perceptions. Ultimately, that can make the difference between a tutorial that walks users through a convoluted UI and an improved design supported by a user guide that adds real value to the customer journey.

Letting your team know you’ve hired a writer and encouraging your team to collaborate with them makes for a much more productive engagement.

Share information freely

When you’ve just brought a technical writer on board to help you with your documentation, it can be tempting to think you need to manage the amount of detail they’re exposed to and avoid overwhelming them with information. Nothing could be further from the truth. Technical writers thrive on detail. We’re also experts at triaging information.

When I start a new project, I encourage the client to share anything and everything they can – from user research findings, competitor analysis and sales decks to backlog items, internal wikis and support tickets. Anything that might help us writers to build our understanding of your target audience, the value that your product or service offers, and the details of how it works is worth sharing.

Sharing this information not only reduces the amount of time the writer will ask for from subject matter experts (SMEs), but also allows us to build a fuller understanding than we would get from only speaking to one or two individuals. More than once, I’ve discovered contradictions and inconsistencies in internal content that reflect a misunderstanding within the organisation. Bringing these issues to light is one of the added benefits that you get when you engage an external technical writer.

Set up a regular feedback loop

Although the actual writing phase is a solo activity, a technical writing project as a whole is a team sport. Typically, writers need input from product managers, developers and other SMEs to clarify details before writing begins and provide feedback on drafts before new content can be published. The issue, of course, is finding the time.

I’ve yet to find a development team that’s not under pressure to keep delivering features, supporting customers and fixing bugs. As with everything else on the product backlog, it’s a question of assessing competing demands and prioritising according to both short-term and long-term goals.

Most technical content is designed to improve the user experience and reduce the burden on your support team, so making time for it is an investment that will help your organisation grow and scale effectively. Just as with development work, prompt and regular feedback is far more efficient than a review cycle drawn out over months.

Inevitably there will be times when urgent bug fixes or critical releases take precedence over other work. However, that caveat applies to everything a team is working on. In my experience, a good approach is for teams to allocate some effort in each sprint to supporting content creation for the duration of the technical writing project. That helps to ensure a regular cadence for feedback and ensures the project keeps moving forward. 

If it helps, treat the feedback loop with your writer in the same way as code reviews. If you commit to doing them regularly and provide feedback promptly, they are far more effective than if you delay feedback for long periods (or don’t provide any at all!).

Creating the conditions for success

Anyone who works in software development knows that it’s a team sport – one where you get the best results by giving those involved the information they need and fostering a culture of collaboration.

The mistake that can happen is thinking an external writer, or technical writing in general, belongs outside that process. In my experience, the more openly you communicate and the more you enable collaboration between a writer and those involved in developing or supporting your software, the better the results for you and for your users.

How about you? What do you find sets a documentation project up for success?