Advice to a solo techwriter

About half a year ago I started as a solo technical writer for my current employer, and I feel that my experience is different from working on a team. I want to write down some observations and advice that I would have given myself.

Your job is now to decide, not write

If a company has hired you as their sole technical writer, chances are they not only need someone to write, they also need someone to figure out what needs to be written, and then write it.

So, you’re not getting paid to receive a Jira ticket and solve it; you most likely need to create the tickets, or even the board for the tickets.

If there is no team, then there is no team infrastructure, and your job is to create this infrastructure, along with everything else that relates to the documentation.

Communicating about your job is also your job

You need to make it clear to other people what is being done.

You might need to set up your Slack channel, your Confluence space, your whatever-your-company-uses area. You need to stake out your little piece of land and plant the techwriting banner.

And then you need to know to whom you are presenting, and what the level of detail is. Generally speaking, a small update once or twice a week in your Slack channel is pretty good so that other people who might be interested can have a feeling for what you’re working on.

Also, it’s a good idea to have a public issue tracker in whatever tool your company uses.

You want to make it really easy for people to open new issues for you. Having a big backlog is a good sign, having nothing in the backlog isn’t. (This doesn’t mean that you need to artificially inflate the backlog; if the company has a technical product, and you’re the sole writer, you’ll have plenty real issues to track.)

People want roadmaps, some people want presentations

This kind of thing depends on the culture of the company, and who you’re reporting to, and at which level you’re presenting your work. You may need to create a roadmap; to treat the documentation as a product and to serve as its product manager. This means having a high-level plan of what’s going to be done, broken down by quarters and themes.

Like:

When communicating about what you’re doing, it should be either completely clear or at least imaginable how these things affect the company bottom line, i.e. how the company is either getting more revenue, or losing fewer opportunities.

Documentation is a big part of developer experience, which in turn is a big part of how likely your product is to sell, so it does play a big role. And it also plays a big role in the cost of support tickets and so on. Your communication may need to reflect what the impact is, not just what you’re doing.

Make friends

Product & Engineering

You should get on good terms with the developers and engineering managers working on the products that you’re in charge of documenting. They are the SMEs, the subject-matter experts, and they will know how the system actually works, and will likely have good ideas on what is not documented enough or what is misleading, what is presented as X but is actually Y, and so on. More to the point, these are the people who can teach you, and since one of the goals is to become an expert (explained below), you’ll find that it is through their knowledge that you can build up your own.

Get on especially good terms with the QA team because they are the ones who know how the system (API, website, SDK, whatever) is supposed to operate for an end user, and since you’re documenting for end users, you’re sharing the same common ground.

Also get on good terms with the product owner or product manager, because they’re supposed to know the why behind a feature, an API endpoint, a web page, etc. They know the industry, they know its challenges, they can give you context.

Solutions, Customer Success and Customer Support

Become friendly with Solutions, Customer Success, and Customer Support, because they usually have to be a) sufficiently good at using your product (API, SDK, whatever); and b) in tune with what customers want and where they are struggling.

A struggling user is sometimes an opportunity to improve the docs, and the bigger the user and the bigger the struggle, the more of a priority it is.

DevOps

Depending on how the company is set up, it pays to have a good relationship with DevOps teams, especially if you’re doing docs-as-code. Ideally you want to be able to go to them and get help in building and deploying things (you will inevitably run into build and/or deployment problems).

Which leads me to…

Ask for help

Asking for help is an underrated skill for many roles, including roles that do have a team, but it’s particularly important when you don’t have a team.

I’ve frequently spent way too many hours trying to do something myself, trying to read outdated Confluence documentation, and trying to piece together things, while all the while, I simply should have asked in a public Slack channel.

My reasoning has always been that I don’t want to waste people’s time & first want to do my own reading. This is valid reasoning, but if after 15 or so minutes you still can’t figure something out, give yourself the benefit of the doubt, and go ask in the damn channel.

Automate things as much as possible

Maybe you have some old system that involves copy-pasting things from another repo to your repo (for example, the changelog). You wouldn’t have done this way but that’s what you inherited with the role.

Invest effort in automating things like this.

You want to use LLMs to the maximum to help you build scripts and stuff around your workflows. You should never do repetitive things manually if you can help it.

Request tooling and access

Always ask for access to things, even things you’re not sure you’re going to use.

Ask for access to the customer support portal so that you have the option to investigate customer tickets. You may not have the time, but when you do, it’s much better to already have access than not.

Ask for access to developer repos so that when the time comes, you can read the source code, and not rely on Slack hearsay.

Ask for access to QA servers, dev servers, K8s cluster management servers, just pretty much anything you can think of.

Sometimes you’ll get a “no”, and that’s ok.

Plug up holes before starting big work

Chances are that you’ll land on some documentation when you start your role.

You may have arrived with great ideas on all the things that you’ll do. Maybe you want to integrate really new cool things, like automated documentation testing by using AI agents.

It’s tempting to go all in on new cool (and useful!) stuff, but in all likelihood you’ll have a lot of gaps to fill, and it makes sense to fill the gaps first before building something super cool.

Some examples of things that should be done first:

The above, depending on how big the company/product is, can take a lot of time so don’t feel frustrated for not getting to the supercool fancy AI automation tooling projects you wanted to do.

Learn to say no

You’ll sometimes simply have to decline some things; this is nothing special to the solo technical writing role, but it’s perhaps more important because if you say yes, you’re saying no to something else that may be more important.

So you need to be able to say “no”, as well as its corpo-friendly variant: “I don’t have the bandwidth right now”.

This also applies to meetings. Meetings, in particular recurring meetings, will eat up so much of your time. So it’s really important for you to say “no” to meetings that you know will take away the time that you’d otherwise spend working on something that’s a priority right now.

Simply say “no” on the invite and don’t explain yourself, unless someone asks specifically.

Again, this kind of depends on the company culture, so you might have a different type of environment, and you might have to fight some more, but generally speaking you should be able to freely decline any meetings that clash with your current priorities.

This obviously doesn’t apply when you’re starting and the meetings are supposed to paint you a picture of how the team operates.

When “no” isn’t an option, you’ll have to say “yes”, in which case say “yes, but…” – and let it be conditional on something, usually time being freed up.

Become an expert

This is likely the most important piece of advice.

You should, with time, grow your expertise around the product. Perhaps not the internal implementation details, but you should know it really, really well.

As Fabrizio Ferri Benedetti puts it:

the basic contract of docs: that someone who understands the system has taken responsibility for explaining it truthfully.

It all starts with understanding! You must know the system, and so a lot of your time should be spent learning it, using it, trying it out, etc. A good indicator is random QA-ish things: do you, on occasion, find a bug in the product and report it? If so, that’s good because you’re getting your hands dirty with it.