One of the things that has surprised me most in my career was the extent to which you may need to advocate for your skills and the utility of your profession within a changing workplace. As a technical writer, it’s easy to say you produce documentation, but “documentation” is a word that means many different things to different people.
Ideally, you have a manager with a clear vision of the work you can produce, strong quarterly goals, and adequate tooling. But that isn’t always the case.
Here’s a story that truly drove home the need to advocate for your profession.
That sinking feeling
“You’re going to have a lot more technical writing like that to look forward to.”
A senior leader said this to me, probably intending to be reassuring. To be honest, I had a sinking feeling in my stomach. I had just spent time working closely with a product manager on a lengthy proposal for a new architectural project. My work included articulating the proposed solution, modeling costs and ROI, and helping to identify potential risks.
The unfortunate thing is that this isn’t what technical writers typically do—in fact, it’s almost the exact opposite. I was helping someone write about what a system could or would be like. Technical writers are trained to dive into how systems work, providing instructions for how to use those systems to achieve specific goals. In manufacturing or hardware, we produce user manuals. In software, we produce the content that ends up on websites like Stripe’s documentation site or MongoDB’s Docs.
Software technical writers are, to borrow a term from Fabrizio Ferri Benedetti, devlings—technically minded people who are interested in and capable of figuring out how a product works to create web-based content that helps users understand it.
The document I was working on was the sort of thing that product managers and business analysts produce. I was happy to contribute because I wanted to be a team player, but that senior leader’s statement drove home something I believe every junior technical writer needs to understand, especially if they are the first or only technical writer at a small company.
Documentation is polysemous. Different people mean different things when they use the word.
Engineers are expected to produce documentation. Managers are expected to produce process documentation. If your company undergoes a SOC audit, controls will need to have documentation. Project leads? They have to produce documentation. One of the unfortunate truths about working in a knowledge-based company is that just about everyone has to produce documentation and they’d much rather be doing the “real work” instead of writing. Support teams are a great source of knowledge, but ideally, they’re turning that knowledge into documentation, too.
It’s not malicious. People will simply see you as a resource to help with their specific documentation needs. You will need to defend your own projects and territory, because in most scenarios, you’ll be at capacity trying to produce and maintain end-user documentation for your company’s products.
Why not draw the line?
If project documentation is a skill and responsibility for other departments, and you’re already quite busy with your core responsibilities, why would you want to help with that kind of project?
In my case, I was having trouble getting authorization for the projects I really envisioned. We were a team in transition. But the main reason was to try and steer the team toward a more mature workflow: it was nice to see a project take the shape of what I would call project documentation.
Project documentation includes things like:
- Business Requirement Document (BRD): Outlines the business goals for a project, typically for stakeholders.
- Product Requirements Document (PRD): Defines features and functionality for developers and designers.
- User stories: Simple, short descriptions of a feature from the end user’s perspective.
- User personas: Descriptions of target users, including goals and pain points.
- Architectural Decision Records (ADRs): Documents the “why” behind key design choices.
- Technical/System Design Documents (TDD/SDD): A blueprint of components, data models, APIs, or technologies for developers and architects.
- Project Charters: Captures who authorized the project, high-level goals, key stakeholders, and project boundaries.
- Project Plans: Outlines the scope, timeline, budget, and resources.
- Risk Registers: Details potential risks, their impact, and mitigation strategies.
- Decision Logs: A record of key project decisions.
I’m definitely capable of contributing to these kinds of documents. I’ve framed personas and user stories in situations where that information was tacit knowledge shared among the team members who designed and implemented a system. I’ve also written project charters, plans, and risk registers for my own projects.
The problem is that most of these documents require a kind of knowledge and involvement that a technical writer lacks. In an ideal world, I’m relying on PRDs, ADRs, and TDDs to write my documentation. The more these documents exist before a product is built, the more knowledge I have when I interact with the released product.
I think one of the unfortunate consequences of Agile escaping into broader business culture is that these kinds of documents are seen as unnecessary steps. This happens when teams forget about the word “comprehensive” and fail to pay attention to the many meanings of “documentation.” Agile was a response to attempts to comprehensively scope out entire projects and rigidly adhere to waterfall schedules. The right attitude is to have “just enough documentation,” and some complex projects require writing to get your ideas on a page.
The core of design, product, and project work is envisioning a future state. To ensure alignment, you need to communicate it. By building a culture where we had clear examples of early-stage documents and working closely with team members to build them, I hoped to help institute a cultural shift that prioritized reasonable product documentation.
This is a bit of an aside: I think one of the shifts with GenAI is that these kinds of docs are starting to fall away. I don’t mean to imply they’re all necessary, but I do think some record of design decisions is necessary once a project hits a certain level of complexity. The interesting thing is negotiating what this looks like with the existing team culture and new tools.
Self-advocacy
I’m not opposed to working in a lone-writer environment. There are lots of things that are exciting and invigorating about these kinds of companies. But there are a lot of competing demands, and you cannot rely on leadership to understand your skills and contributions. This is even true in cases where you work embedded in a team.
For this reason, having a game plan for self-advocacy is crucial. If you’re a technical writer like me, this probably doesn’t come naturally. The idea of self-advocacy can feel like selling or bragging, which I’m personally uncomfortable with. Here are some steps I’ve committed to that help me advocate for my work in a way that feels authentic and comfortable.
One thing I plan on doing is using the words “documentation” or “docs” less when I describe my contributions. As much as I love Write the Docs as a community, “documentation” has too many possible interpretations. Terms like “feature-specific user guides,” “API references,” “installation guides,” and “quick starts” are all much clearer.
Here are a couple of things I plan on striving to do, whenever I join a company:
- Build a strong, shared understanding of my role with my immediate manager and create a plan for how I can be assigned work. Having a sample process document that you can adapt to new environments is a great conversation starter.
- Find a time and way to introduce myself and my expertise. It may be a short presentation explaining what skills I bring, what kinds of work I’ve done, and my process for working with other teams. This helps set up guardrails and channels for incoming work. It’s also important to build relationships with key customer-facing teams in addition to your developer and product management teams. Most importantly, this presentation will emphasize the value of product docs for all roles in the company. If product documentation explains what and how are product works, it is a helpful knowledge resource for marketing and sales. If this isn’t an opportunity, I’ll build my own profile in Confluence or SharePoint, so that people can understand my perspective and skills.
- Be engaged and champion our content in Slack/Basecamp/Discord. I’ve been in situations where people have asked questions like, “What are the differences between these three features/products?” in our group chat. It’s a good question that points to a confusing area in our product, and I think they genuinely didn’t know that good documentation sites can help resolve those kinds of questions. By answering these questions and championing your site, you’re increasing the visibility of your work.
- Celebrate contributors. Knowledge is a shared enterprise. Building relationships and celebrating team members who take to the time to give you good feedback is important for driving adoption of your work within the company. By expressing gratitude and value for colleagues who contribute feedback, you can build a culture where leadership acknowledges the value of your work.
- Maintain a log of my wins and lessons.. I try to keep daily notes on my work. It’s important to round these up into wins and lessons. It’ll help when I meet with managers to talk about my work. Along with that, find a way to measure outcomes by collaborating with support and other customer facing teams.
- Show up for engineers and PMs. These teams are the core of what I do. While I’m building advocacy and learning, it’s important to collaborate and work with the engineers who build the products I’m writing about.
This is a starting point, but these commitments build a practice of self-advocacy that doesn’t feel like bragging. They help build recognition for your work beyond your immediate team and foster a culture where your contributions are understood and valued.