#topic/writing #max/lessons-learned #path/career

What I’ve learned in my 10 years of writing for work

This is the full version of this post. You can also see the condensed version on LinkedIn.

Documentation is like technology in how you bring it into use.

You wouldn’t adopt technology just to have new technology (I say, knowing people do this): You should review its purpose and what it can do for you, try to understand what problems it will solve.

Are you creating a potential problem just to use this new tool? Or can we use it (or another) to solve an existing problem? Have you tested/explored to make sure it works in your current systems/workflows? Is it capable of doing what you want it to?

Having documentation “just to have it” is very useful and good; you will never hear me say “we don’t need a guide for that” unless I’ve already found guidance elsewhere to use instead. However, you also must consider what problems it will solve, how people will use it, who will use it, and how it will integrate into their workflows and processes. (Also, your time and energy are limited. Don’t document everything.)

People don’t like to read documentation.

They want the work to be easy enough that they don’t have to reference a guide. If they must, they want the guide to both be very simple, non-technical, and easy to use, but also detailed enough to include everything they need to know. Good luck out there.

Use colors, tables, workflows, and images.

Don’t overdo it, but these can save a very confused person very easily. A writer may process information better in a bulleted list but someone using the guide for a quick glance on what to do next isn’t going to want to read all that. And because they don’t want to, it now feels like the task of looking for help just got harder. Drop an if/then workflow image in there to guide them on where to reference what they need.

I like to use callout boxes for showing different types of information, for example: troubleshooting tips (yellow), warning/pay attention (orange), additional notes/not urgent (gray). There’s a key the team can use so they know what they’re looking at, and they only read the box if they need to.

Learn about accessibility.

Accessibility serves everyone. You don’t know how a coworker needs to zoom when viewing your guides. Someone else may have other needs. Design and write for everyone in your audience, keeping in mind that you don’t know what future guide users will need.

It’s easier than you think, by the way, and it’s okay if you don’t get it perfect. As you do it more, you’ll learn and improve over time.

Clear expectations are vital for a documentation system to function well within a team.

If it’s not in the guide, some people will want to be able to blame the guide if they missed a step or did something wrong. It’s very important for work expectations to align with doc expectations.

Work with team leaders to make it clear what problems the guides will solve, and what the audience is expected to do or remember without explicit guidance. (This is something you can easily fit into your onboarding.)

Use Evergreen content.

This is especially if documentation is not part of your job and you’re doing this to help the team, but generally as best practice as it makes maintenance easier over time. Evergreen content is always relevant, so it’s no time-based or specific. Instead of “last year,” use “in 2023.”

Trust me, those little mentions of process changes and technology updates add up over the growth of your docs. You don’t want to find yourself in a situation during editing where you find one you missed and need to figure out when you wrote “last year” so you can update it to “in 2021.” Wouldn’t it be better if you don’t ever have to update it after first writing it?

Make a simple style guide that includes tips for non-writers.

This will go so far for consistency when you have team members who only have to create docs every once in a while, or who hate doing it. You might have a bigger style guide that your more dedicated writers use, but “ain’t nobody got time for that” people will still benefit from a 2-3 page job aid.

Your audience is someone who hates writing but needs to produce something that doesn’t need to be updated within six months (or whatever your audit cycle is).

Survey your users at least once a year, especially after hiring new people.

The needs of your guide audience changes as new people come in. Find out how they are getting to the information they need and make it easier for them to find it that way. Find out what information they expect to find and either add it or measure expectations.

Serve your audience in how you outline and organize your guides.

This is a long one.

Consider your audience not just in their technical knowledge, but also:

What is the most important? What should be emphasized and what is referenced as needed?

I’ll use my current experience as an example: We don’t print our guides, they’re all on the computer – Word, SharePoint online, some video tools too. We have 3-4 locations where we store guides (organizational problem) and try to keep the file structure consistent for ease of use.

It’s true that people can use organizational elements such as tables of contents as a logical starting point for accessing the content they need. However, I’m finding that most of the people I’ve worked with use keyword searches. They probably don’t even know where the guide is located because they access it by using the search bar every time. It’s bookmarked, or they simply visit the doc library and search for it there.

Make a user experience journey for your guide audience.

My goal is to make sure they can get to the content as quickly as possible, that the guidance is current, comprehensive, and accurate, and that they can complete their journey to the solution somehow. If the guide doesn’t have the information, it tells you where to get it.

When I look for content, as the person writing it, I know exactly where the guidance is. I also know how to get to it through the folder structure, and that’s usually what I use to get to things. The people who are using your guides might find information differently than you do, especially if they are not helping to maintain the library.

Here’s what most of my audience does:

  1. I am doing work, but I’ve come across an issue.
  2. How do I describe my issue?
    1. I’ve never had this issue before but I can vaguely describe it
      • Derive KeywordA, KeywordB, KeywordC and drop one or many of these into the search bar
      • Click through the list of results to visit various guides and see which one matches my issue
    2. I am familiar with it & need help
      • Put the guide name into the search bar, open the guide
      • Keyword search to find the content within the guide
  3. Use the guidance. If there is no guidance yet, do the next steps.

To serve your audience, make their journey part of the decision of how you outline.

My audience for ages has been a support team and they need the most important stuff on the top and the rest below it. They don’t want to read the entire document, sorry. If your audience requires a textbook-like experience to read the document beginning to end, then please do order it logically.

A support team doesn’t start with the guide, they start with a problem. As a writer with a good sense of structure your default is to organize the information in a logical order, but sometimes you have to override that for usability. As always, it depends on your audience. Since they’re doing mostly keyword searches, I make sure to use multiple terms to describe the same thing or I’ll put a keyword list at the top of the section.

Because keyword search is usually exact, it’s important to keep in mind how the audience holds that taxonomy. You’ll find they’re using multiple terms to search, so here are a few tips to keep everyone consistent:

I still have a lot to learn. No one can be an expert on all things writing.

In the last year I’ve been writing for multiple audiences using various platforms and learning as I go. In addition to support teams, I am now serving technical teams, instructional designers, academic directors, and others here and there. I love the opportunity to expand my horizons and help so many people with their daily work.

If your audience defines your work, then that audience will be too diverse and varied to ever be “done” learning how to write better.

Every technology team should have a documentation person.

As technology evolves and serves new needs, or eliminates old problems, people also evolve in their needs and problems. The documentation library has to evolve with its users just as any other system would need to have releases, updates, or patches.

This is a full time job. As a result, your team will have someone keeping the guides up to date, pointing out process issues, alerting leaders to outdated information for clarity, who also has to know the in’s and out’s of the technology the team uses, and therefore can serve as part of the platform support team. The writer can work with the product managers and take care of the support staff as well as the end users.

Pay them well, give them a good work environment (and a work bestie or two), and you can rely on their historical and organizational knowledge for years to come. A tech writer is simply a reporter. I won’t complain about the process changes, just tell me what I need to know so I can update all the appropriate locations and help support the team.

Introduce your doc person to your UX person so they can be work besties.

They’ll have a lot of the same frustrations and can put their heads together to find solutions that serve everyone. At least that’s what happened to me.

Created: 4/17/24