What is a Technical Writer?

A technical writer is the glue between users, developers, marketing folks, and tech support. A tech writer knows a little of everything. A technical writer carefully cultivates a broad lens on their product and fills the cracks that no one realizes exist. A technical writer must exert an invisible, gentle, but ever-present force that moves their product in a user-focused, data-driven direction. A direction where not APIs but mental models rule, the user is a constant presence, search brings up the right information, and the interface moulds to the user.

A technical writer’s actual job is not writing. The writing itself is easy. Writing must be minimalist (not minimal) and example-driven. Get to the point. Get users trying commands early. Show them how to recover from mistakes. This much is canon today.

A technical writer’s true job is to perfect complement their dev team. Now that’s a hard job because it requires combining several different things, including great people skills.

• Your dev team can be supported support on several fronts:
• Convey the user perspective to developers
• Provide quick feedback on APIs
• Test APIs for error handling and help smith error messages
• Learn about their users and their mental model
• Additional research on user tasks
• Explain importance of naming on SEO
• Write doc that has a clear call to action, is concise, and follows user mental model

This is a technical writer’s job. The term “Technical Writer” can feel like a misnomer since it lends the impression that all writers do is write..

Feedback on APIs

A technical writer should diplomatically push the user perspective. Developers can forget about the user perspective for several reasons. They may feel that to satisfy a use case, providing an API is adequate. However, there can be considerations of how the API fits in with existing APIs.

For example, there might be an existing function that users are very familiar with. Do you extend that function or add another function? Here, a technical writer knows the user mental model at a granular level of detail. While the developers may not see enough user feedback to have the  mental model that you do. The marketing manager is familiar with what important clients say but will not have the same granular familiarity. UX doesn’t know the technical ins-and-outs. Only the technical writer can tie it all together. Since the technical writer knows what it takes to educate a userbase about a new function, you know how functions can get too complicated to use effectively. Other times, developers get distracted by technical details of implementation and rule out a solution, when the technical pain could be worth the result. You have to rely on use cases you’ve been collecting, or do the research, create an argument for what you think users will want, and talk to the developers, first 1:1 and then as a team, to get them on board or understand their point of view. You need to judge where to expend your political capital.

Remember that your success depends on whether you’ve been cultivating a relationship all along and on whether you showed your devs evidence for what users want.

While designing APIs, it’s essential to remember the “API conundrum”. You cannot design an API without user input. But once users start using the API, they get mad if you change the API. Hence, designing effective APIs is impossible. This is solved by UX testing. Unfortunately, most teams lack resources for UX testing. That’s why it’s essential for you, the tech writer, to do research, try things, and provide timely feedback. You can really make a difference for your dev team.

User’s Mental Model

As you spend time on your product, you’ll notice gaps where the user’s mental model or expectations will not fit your product. Here, you provide feedback on the user’s mental models and the implications for existing APIs. Raise the developers’ awareness and and show use cases as you discover them. You will have to save these use cases somewhere, so develop a system. To discover use cases, keeping tabs on forums and then saving them is work. That’s why this is the hardest part of your job. You need to choose which gaps are most important and focus on creating awareness around those. Hopefully, by mentioning a gap enough and judiciously expending political capital, you can initiate discussions between your devs and make change happen. Make no mistake though, this takes a lot time time. Hence the ion engine analogy.

API Evolution

Generally speaking, your product’s API has a finite lifetime, maybe months, years, or decades. As your product’s needs evolve, the original API will become unsuited to whatever users are throwing at it. Your team will extend the API to accommodate users, but things will grow increasingly unwieldy. At some point, the API’s drawbacks cannot be ignored. Your team will begin working on a wholly new API. At this point, two things can happen:

1. Your team deprecates the old API and forces users to migrate
2. Your team keeps the old API around, probably forever because users have tons of legacy code

#1 makes users very unhappy for obvious reasons and is generally not recommended. You should advocate against this. Instead, you and your team need to design a migration plan. Which workflows/use cases/users need to be migrated? Are there important users that marketing and support can target? What are the points where users can be told of the new API? For example, in doc, or in warnings/errors, or in GUIs etc. How can users be migrated in the smoothest possible way? How do you measure user adoption of the new workflow? What combination of carrot and stick will not make your users too unhappy? Because, ideally, you do not want to support two workflows for ever. Now, in this migration, the technical writer can really shine with their knowledge of the user perspective. They can answer questions like: Which workflows are easiest to migrate? What APIs can we deprecate first? How can doc/errors/warnings/GUIs be used to alert users? How can the user interface appropriately direct users to documentation to guide them along this transition? How can users be convinced by presenting the benefits of the new workflow from the user perspective? Is there a “wow” factor that get can users on board?

Of course, in designing the new API, the technical writer must be fully involved in ensuring that all the gaps they are aware of are take care of. That is the point of a new interface.

Building a Relationship with Devs and Communicating with Them

From the first day, you need to work on your relationship with your developers. This starts with an in-depth 1:1 conversation with each dev on what their perspective on documentation is. Do they think doc should contain every little detail? Should doc start with lengthy preambles or get straight to code? Should a page have every possible example or take a tight approach? How important do they think doc is? Once you start engaging your devs, you’ll build trust and confidence. Without this trust and confidence, you will be unable to advocate for the user. Try to:

• Show developers data: Show them how far down a page users scroll, what feedback users leave, what kinds of pages users like and dislike, what users like in documentation, what use cases you find on forums etc, what other people are saying about documentation, how users really like MATLAB’s doc etc.
• When you write doc, take your devs into confidence. Discuss approaches with them and explain why you prefer a certain approach.
• Ask them what user workflow they had in mind when designing an API. Ask them questions if you can think of issues with the workflow.
• Explain in detail what your research on the internet has shown with links to sources
• Explain why your doc is minimalist and does not address every single possible use case. You might have to spend a lot of time explaining this but it’s worth it to build the relationship.

How to Write Documentation

• Why is the documentation required?
• What the audience? What do they already know?
• Carefully read spec and check if implementation is consistent with requirements.
• Iterate on:
  • What’s the current workflow?
  • Research users/tasks yourself
  • Try out tasks/talk to devs
• Try to generate errors and check messages for sense
• Check that inputs and outputs have form that users expect
• Check that outputs can be used in next stage of user workflow
• Link doc appropriately. Just the right # of links.
• If time, imagine possible enhancements requested by users, and then consider if the API provided is easy to enhance.

SEO

• SEO is complex
• Ensure your pages rank for the most common searches and don’t worry about the rest
• Post answers to any forum pages that rank highly
• Consider creating your own forum pages if necessary to target alternate keywords
• Title, URL, first sentence are essential

Learning Your Users’ Mental Model

• Monitor TS requests. Your team might not always drill down to the true cause of the user’s problem. They might provide a workaround and consider the TS case solved. You need to ask “Why did the user go astray?” Often the issue isn’t with the user not RTM but with the API not meeting user expectations
• Monitor the support forum your users use, such as StackOverflow or MATLAB Answers. Setup a filter to automatically be alerted of posts on your product using a service such as Blogtrottr. Read each post to understand your user’s expectation and why they ran into a problem, along with the task they want to perform. This is how your learn about users, their expectations, and their mental model.
• Create a task/note to track every issue you learn about and collect use cases their, even if your devs have no plans for action at that point

Teaching Users How to Code

This sounds crazy but users learn coding best practices from doc. Unfortunately, doc has things like:

for i=0; i<5;i++ % 5 is a magic number

A user runs with this and will enter

for i=0; i<(myfun(2)+20/3); i++ % bad

How do we teach best coding practices in code? By showing:

Num = len(arr);
For i=0; i<len; i++

Adopting of New Functionality by Users

When solving user problems, one perspective is that providing a good API solves the problem. From a tech comm perspective, this is the beginning. The real challenge is getting users to use the new functionality and use it correctly. Because, while there are established and widely-accepted principles for writing code and designing interfaces, there are no principles on user adoption. It can feel like a jungle out there. Yes, there are a few best practices, but those are just getting traction in large organizations. So the technical writer plays a large role in ensuring users use the functionality correctly. Through doc and forums, you can nudge users to adopt your product. And you can be instrumental in growing the user base. That is why tech writers are the ion engines of product development. We work in the background and our contributions aren’t “big bang” but they are steady and effective.

Again, from a tech comm perspective, providing an API is the start. Generating user awareness and getting users to use the API correctly is the battle.