Home »

Write the Docs Newsletter – May 2025

Hello, fabulous documentarians! I hope you all are doing splendidly and getting plenty of rest, whether you’re filled with ideas from the Portland conference or spending time with yourself or loved ones. Anyway you can get it, finding time to recharge is always important.

If you get energy from being around other documentarians, you’ll be delighted about our new conference: Write the Docs Berlin, which will take place October 27–28 and will have in-person and virtual experiences. If you find onsite events to be stressful, you may be interested in the entirely virtual Australia conference, November 20–21. Whichever conference you choose, you’re sure to find lots of ideas and great people. So choose now and start planning.

Outside the world of conferences, the 2024 Documentation Salary Survey results are out! For all the numbers, head over to the 2024 salary survey results.

This month’s newsletter has articles on the least you can do for internal docs, why or why not to put a gate on your docs, where documentarians fit in organizations, and how to filter out AI submissions for hiring. Enjoy!

Minimum internal documentation

Capturing and sharing knowledge that resides primarily in the minds of engineers is challenging and scales poorly. If engineering discussions and decisions aren’t documented, downstream teams will struggle to extract these insights later in the software development process. One idea is to define a minimum set of internal documentation that product teams should create during software iterations.

Consider developing some guidance for the contents of internal documentation. Engineers often focus on details, so encourage them to think about new features at a higher level. Provide a template to help engineers document essential information easliy. Some have experimented with using structured data files (such as YAML) to create manageable specifications for various interfaces and facilitate engineering contributions to internal documentation.

Another approach is to require certain minimum information in the tickets for public-facing docs, which would serve as a loose kind of internal documentation. You could require docs tickets to include context and descriptions, clear acceptance criteria, links to pull requests and associated development tickets, and links to resources such as user stories, product requirements documents, code with comments, meeting notes, and product demos.

Fixing the knowledge transfer problem usually requires leadership support and a cultural shift. Engineering teams often develop new features under tight deadlines and internal docs fall by the wayside. Talk to those who are affected by the lack of internal docs, including engineers. Assess the time and resources that are lost to tracking down information and pausing work to explain things to other teams. Address the misconception that Agile practices do not require documentation. These conversations can help demonstrate why the time spent on internal documentation is time saved in the long run and can help you get buy-in from leadership.

See more Write the Docs resources about writing topics.

Locked out: The effect on users from gated product docs

Imagine you’re trying out new software and want to learn how to use it. You go to the website looking for a guide – but before you can read anything, you’re asked to log in. Frustrating, right? This raises a big question: Should product documentation be open to everyone or kept behind a login?

Some companies lock down their docs to protect private information or keep competitors from learning too much. In some cases, the product might include sensitive data or the company might need to follow strict rules that require extra security. Others think login walls help keep AI tools from copying content and using it in ways the company can’t control.

But hiding docs behind a login may cause real problems. Users get stuck or give up when they can’t quickly find help. It’s harder for people to find answers through search engines and support teams get more questions they shouldn’t need to answer. Even paying customers may forget their passwords or struggle with login steps.

To better understand the impact of gated content, it helps to weigh the pros and cons.

Pros:

  • Protects private or sensitive information.

  • Controls who can access content.

  • Helps meet security or compliance needs.

  • Allows you to track usage.

  • Enables more personalized content.

Cons:

  • Makes content harder to find.

  • Slows users down or frustrates them.

  • Increases support requests.

  • May make your company seem less open.

  • Limits community engagement and sharing.

One solution is to split the difference: keep private or advanced content behind a login but make basic guides and key references public. This gives most users what they need without giving away too much.

Ultimately, deciding to gate documentation depends on balancing security needs with user accessibility. You want to provide the best possible experience without compromising essential information.

See more Write the Docs resources about writing docs sets.

Where do documentarians “fit” into an organization?

Except for startups, most companies have established organizations. Documentarians’ role in relation to the company’s products may determine their department. This is often the department that most closely aligns with what they’re expected to document (type of content and audience).

Once you start working for a company, you may not have the option to move around unless you are a lone writer or part of a small team. Being in the “wrong” department can affect a your success. (Are you managed as a writer with relevant success metrics?) Who you would report to is something to discuss in an interview before joining. (What’s the chain of command for this role? Would my direct manager have experience working with writers? Could I work with people in other departments?)

In general, documentarians find themselves in one of two departments:

  • Marketing: These writers may focus more on customer-facing or company-oriented documentation and may work directly with other writers in the Marketing department. You may need to use tools used by others in the department instead of specialized tools. While the buy-in for documentation may be higher, Marketing may be considered a “cost” center and may experience more budget constraints and job insecurity.

  • Engineering: Often these writers focus on internal documentation for the department or create documentation for technical products (such as API documentation for developers). They may work directly with product managers who are part of the Engineering department. Working in Engineering may mean higher pay, more job security, better equipment, and access to better tools.

Other options include Customer Support and Customer Success. In a small company, a documentarian may report directly to the CTO or CEO. This can be beneficial if you’re experienced and independent, but others may not get the support they need as a technical writer.

See more Write the Docs resources about jobs and careers.

Filtering out AI in hiring tests

When hiring someone to take on a documentation (or other) role, you may have some sort of writing or editing assignment to get a sense of the candidate’s skills (though you should never use candidate work in your actual docs without paying the creator). While many people have used such tests for years, some have worried that AI tools make it impossible to tell if candidates can actually write or edit.

People generally agreed that such tests don’t get at the things that make documentarians good at their jobs. But they can be useful in filtering out fraudulant applications. So how to structure them to still work?

Some advice focused on asking people to explain why they did certain things in the assignment at an interview. One suggestion was to ask candidates to specifically use an AI tool and talk about how and why they did. These ideas are great for in-depth understanding, but require more time and are less useful as an initial filter.

Others suggested not to base tests on existing technology – there’s too much already written and so classic plagiarism or its new form (AI) will have an easy time with it.

There was some discussion of live-writing exercises, where candidates write in front of you, but some worried it was a specific circumstance unlikely to be repeated at work and might not capture the same skills.

Some suggested being trickier and having the assignment include hidden text with specific instructions to LLMs, such as to include somethng irrelevant in the response. If the content is there in the submission, at the least you know the candidate didn’t check before submitting.

The general consensus seemed to be that there isn’t one approach that would work in all circumstances. Determine what skills are most necessary for the job you’re hiring for and focus your efforts there. Almost all of your candidates will use LLMs in some way.

See more Write the Docs resources about hiring.

Write the Docs resources

Write the Docs offers lots of valuable resources related to documentation. See all of the Write the Docs learning resources. To discuss any of these ideas or others related to documentation, join the conversation in the Write the Docs Slack community in one of the many channels.

Events coming up

Announcing Write the Docs Berlin 2025   Portland 2025 Recap - Talk Videos, Photos, Sketchnotes, CoC Report