I’ve been working on a project at work to help my company define roles and responsibilities for technical writers working in open source to help with contract negotiations.

Originally, my goal was to create a comprehensive list of possible tasks that tech writers working in OSS might possibly work on. Then, I planned to crowdsource that list with the open source writer community on Write the Docs.

I kept getting comments like, “Wow, we really do a lot of work, don’t we?” and a number of people told me they copied the list to share with their employer. Based on those reactions, I realized that some of what I’ve produced while working on this project could be of interest to a broader audience. So, I’m capturing some of this work here in the blog to share it more broadly.

Tasks that OSS writers might be asked to do

For this list, I was erring on the side of being comprehensive. Not all writers will work on all these tasks in every project.

New documentation

• Create documentation for new features in an upcoming release
• Review and suggest edits on new documentation created by developers or community members
• Create standardized templates that developers or community members can use to create new documentation
• Write tutorials, getting started guides, best practices

Documentation quality

• Create supporting quality guidelines for the documentation including creating and maintaining style guides, contributing guides, glossaries, etc.
• Triage new documentation issues
• Resolve documentation bugs
• Groom the documentation issue backlog
• Identify and label documentation issues that community members could work on
• Identify and archive documentation that has gone stale
• Use docs analytics to identify areas for doc improvements

Information architecture

• Improve documentation organization and content strategy to make the documentation easier to search and navigate
• Create a content reuse strategy (NOTE: This task can get especially complex if some of the open source documentation is consumed upstream by proprietary software)
• Curate documentation content
• Create documentation meta-data

Release management

• Track release dates
• Prepare documentation for release
• Create release notes or changelogs
• Establish docs policies and procedures during code freezes
• Test the final docs release build before publishing a new release
• Release announcements

Community management

• Organize and run community documentation events
• Organize and run documentation working groups
• Participate in community events and conferences
• Engage with the community on community forums
• Create or maintain community support documentation (Contributing guides, READMEs, Code of Conduct, issue and pull request templates, CODEOWNERS docs)
• Provide advice to community manager(s) about communication strategies
• Help community members set up their environment to contribute
• Write or review website copy
• Determine how to reduce the barrier to entry for contributing to the docs or to the project in general
• Write blog entries or support developers who write blog entries

Documentation epics

• Record requests from community members and stakeholders for large documentation improvements (epics)
• Work with product manager to triage and prioritize requests for doc epics and determine which ones to work on

Docs tooling

• Understand each tool in the docs toolchain and what they do
• Help new community members onboard with the docs toolchain
• Implement tool-level documentation quality measures (linting, CI/CD)
• Troubleshoot doc tool issues
• Automate documentation processes
• Updating to new versions of documentation tooling
• Set up URLs for documentation content
• Handle URL redirects for updated/change/archived content
• Update to new versions of documentation tooling

UX

• Conduct community user research (surveys, interviews)
• Identify user personas
• Identify user journeys
• Provide guidance on error messaging or other in-product UI text

L10n

• Localizing the docs into different languages

Challenges of writers working in open source

In addition to the standard challenges experienced by most technical writers in this profession, OSS technical writers have a variety of additional challenges that are unique to working in open source:

Many open source developers have a wide variety of responsibilities and they may expect writers to have the same flexibility. Due to their non-profit status, many open source teams are understaffed or are asked to do more with less. Developers working in OSS usually have to develop competencies or generalized skill sets outside of the traditional developer roles: building CI/CD systems, QA testing, packaging, product management, release management, technical support, community management, and (yes) writing documentation.

In that same vein, OSS technical writers are generally asked to take on a wide variety of possible tasks in communication-adjacent areas of responsibilities that technical writers traditionally don’t work on: community management, technical support, etc. Many OSS technical writers find themselves in a situation where they need to negotiate or set expectations for developers that have never worked with technical writers before.

Technical writers often join projects that are either very young or very mature. Some technical writers might be brought into young projects that have very little documentation at all, which means the technical writer might have to build an entirely new documentation system and content strategy from the ground up. These writers might also find themselves in the position of constantly having to translate “tribal knowledge” into technical and community documentation.

On the other end of the extreme, some technical writers are brought into projects that are fairly mature and well-established, which means there might be a lot of existing documentation that has already been created by developers or community members. The consistency and quality of this pre-existing documentation can vary widely–from poor to excellent and everything in between. Tech writers may find they need to develop standards and audit the existing documentation to ensure it is compliant with these standards. Typically, another large pain point is the lack of a clear content strategy or information architecture strategy, meaning how well users can search and navigate the documentation to find what they need.

Most open source projects use either custom-built or open source toolchains for their documentation. Open source documentation toolchains have many distinct advantages, such as their low cost and their compatibility with docs-as-code documentation systems. But the biggest weakness is that they are generally quite complex and they require a high degree of technical competency to set up and maintain. Not all technical writers have these competencies, which can often be a major barrier to their success. On the bright side, open source toolchains are usually supported by a larger DIY community that technical writers can engage with for additional resources and technical support.

Technical writers often interact with the open source community. Technical writers working in open source are in a unique position where they often interact directly or indirectly with the OSS community by participating in community events, engaging on community forums, onboarding community members, reviewing community pull requests, and adding comments on issues opened by community members. These interactions add a lot of unique challenges and stressors that technical writers in proprietary software are mostly shielded from. Interacting with community members can be time-consuming and often requires excellent people skills (especially when dealing with frustrated or angry community members).

One thing that I like to emphasize to stakeholders with less knowledge about OSS is the fact that interacting with open source community members is quite different from interacting directly with proprietary software customers. According to Nadia Eghbal, community members can include four or more distinct types of community member segments:

• Passive users, which are roughly equivalent to users/customers in proprietary software.
• Casual contributors, who are users/customers of the software and who also file issues/bugs, interact on community forums (typically asking for support), and may occasionally submit a documentation-impacting pull request that requires technical writing review. Sometimes, interacting with casual contributors can be quite resource intensive while offering little value to the project overall. All OSS developers and writers need to guard against over-helping this particular user segment and should set appropriate boundaries.
• Active contributors, who are community members that actively engage in the community in many possible areas: development and documentation support (in the form of pull requests), technical support (by engaging in community forums), and who may derive their income from the open source project in some way (such as by acting as a professional services group for the technology stack or providing paid training on the technology).
• Core maintainers, who are the key members of the community or development group that are necessary for the project to function. Core maintainers have the deepest understanding of the project’s technology toolchain, its development history, and the history of the community. As the most crucial and valuable members of the project, supporting these team members and protecting their time is extremely important to the success of the project.

Guiding principles

Part of my purpose in creating the list of tasks is to determine what the guiding principles my department should use when negotiating which tasks are in or out of scope for technical writers working in open source. I don’t know what my company will ultimately decide, but I want to define for myself what I think these principles should be:

Technical writers bring a unique set of skills to a project and it’s important to use these skills efficiently and wisely. To me, that means making sure that technical writers are devoted to higher order technical writing tasks such as information architecture (IA), UX content writing and research, and working on global documentation improvements (doc epics). Most developers usually don’t have skills in IA or UX and they generally don’t have the time or inclination to make badly needed global improvements. For that reason, developers should generally work on lower order documentation tasks (such as minor documentation fixes and first drafts of new content) and technical writers should work on these higher order tasks.

Don’t treat your technical writer as a secretary for the developers. That means you shouldn’t farm out any and all content work to writers simply because some writing might be involved. The joke I sometimes make is, “So, let me get this straight: you want me to use my Master’s degree in English and pay me my hourly rate to take notes at your community meeting? Okay, if that’s how you want to spend your money, then that’s fine. I mean, it seems like a waste of money to me, but I can certainly do that job if you really want me to!”

Another common phrase I repeat is, “Sure, I could work on that task. But just be aware that it would come at the expense of other documentation tasks that have been earmarked as my top priority by the product manager. Do you want to tell the PM or should I?”

Task switching is destructive to quality work. When you ask any employee (let alone technical writers) to take on too many different roles and too many types of tasks, you risk creating inefficiencies in your system. In the same way that factories need to carefully manage changeover times for machines in order to prevent production waste, knowledge workers need uninterrupted time for deep work and focus. If you ask a team member to be a generalist and constantly switch contexts for each task, you reduce that team member’s overall effectiveness. Try to avoid doing that with any employee, let alone technical writers.

Above all else, technical writers should reduce the burden on the core maintainers. As I mentioned earlier in this post, core maintainers are the most important members of the open source project and they are crucial to the success of the project. The ultimate goal of any technical writer should be to support the core maintainers of the project so that they have the time and energy to work on tasks that are necessary for the maintenance and growth of the project.

That does NOT mean that the technical writer acts as the maintainer’s secretary or takes on the annoying little writing or communication tasks the maintainers do not want to do. Rather, it means that the writer is working to produce documentation that will:

• Help project contributors onboard more quickly and begin making meaningful contributions to the project, which spreads the workload more evenly across more people.
• Make the software self-supporting and easier to use, which reduces the amount of time maintainers spend providing technical support.