Home »

Write the Docs Newsletter – November 2023¶

Salutations, documentarians. I hope you are able to find things in your life to be thankful for and also the time to be able to appreciate them. I’m thankful for the wonderful community of documentarians at Write the Docs and the insights they freely share with us every day.

Have you filled out the 2023 Documentation Salary Survey yet? If you have, we appreciate you – is there a friend or colleague you could spread the word to? If you haven’t, please consider adding your data – the insights become more valuable with every submission.

A special call to contractors, freelancers, and self-employed people: to publish meaningful median rates, we still need a lot more data - so if you can think of any other spaces where your fellow contractors and freelancers might gather, please share the survey link. The questions for non-employees have been updated to cater to a variety of independent work situations, and if they don’t fit for you, please let us know in the feedback section of your submission how we can make it better.

In conference news, the Australia conference has now published its full schedule. Be sure to book a ticket while you still can. And the Portland conference has announced dates for 2024, so you can start making plans already.

The newsletter this month covers whether and how to publish logs of changes to docs themselves, how the organization of docs teams might affect people on them, and how to measure the quality of docs.

Changelogs for Docs¶

Technical writers often publish product-focused changelogs or release notes that describe new product features and fixes but may also publish changelogs that list new and updated content in the docs themselves. Tech writers might need to provide a docs changelog to satisfy standards like ISO, inform technical support engineers of new docs that can help with support cases, or ensure that stakeholders like marketing and product know about docs they can refer to in their materials. Docs changelogs are also useful for highlighting the quality and volume of the work the docs team does, building goodwill, and enhancing the team’s reputation throughout the organization.

Some writers collect their own commit messages as the basis for docs changelogs, either manually or with a tool based on a standard like Conventional Commits that helps automate changelog builds. The TinyMCE changelog is an example of a commit-based changelog. Others rely on features that are built in to the documentation tools they already use, like page histories that make it easier to figure out what changed. When you’re deciding what to include, consider focusing on new content and substantial updates and perhaps omitting typo corrections and style changes.

Distribution methods for docs changelogs naturally depend on the intended audience. For example, you might share an internal-only changelog via the company Slack workspace or other established employee communication channels. For external audiences, the changelog might be published in the docs or posted in the docs repository.

Doc Team Organization¶

The organization of a documentation team can have a significant effect on team members. As a manager, you may want to review your current setup; as a documentarian, you may want to consider the structure before joining an existing team.

One aspect to consider is the ratio of more experienced to less experienced writers. Some teams expect more experienced writers to train less experienced ones. The larger the team is, the more likely it is that writers can be matched up.

Another consideration is whether specific writers have assigned roles (such as writing, editing, reviewing, or automating procedures). Some teams have generalists, who can also support the team with specific skills. Other teams have specific assignments for each member. A manager may be responsible for filling in gaps.

Besides roles, you may need to consider if writers have responsibilities for the full product line or for specific products (or features). When all writers are familiar with everything, workload balancing can be easier. One person mentioned assigning specific products or features to newcomers, but expecting more experienced writers to be available for all products.

To complete their work successfully, documentarians interact with others. When assigned to a product, the interactions may be limited to product managers. With features, writers may need to interact with very specific subject matter experts. Through these interactions, documentarians can develop their skills, get known throughout the company, and demonstrate professional growth.

But what happens when products or product lines change? See Keeping Up-To-Date with Necessary Changes for dealing with ongoing changes. A manager needs to be aware of significant upcoming changes. With timely communications, writers can develop the skills needed to document new features or products.

Measuring Docs Quality¶

Evaluating documentation quality is a common practice, but it often presents a unique set of challenges. A recent conversation shed light on the complexities involved in this process, offering insights into how to approach it effectively.

One person shared the dilemma of having to rate hundreds of articles in their knowledge base for quality within a tight timeframe. The request came from their CTO, who believed it would only take a few minutes in total.

The conversation revealed a range of questions and concerns. First and foremost, people wondered about the purpose behind such an evaluation. Some speculated that it might set a baseline for future improvements, while others considered it a potential case for securing additional resources. Without clear initial motivations, the task becomes much more challenging.

Some suggested the development of a rubric to assess documentation quality, focusing on criteria like use case examples, information clarity, and adherence to a style guide. One person shared a checklist with a structured approach to the assessment process. The categories were:

Findability
Accuracy
Beginner-friendliness
Layout
Task-orientation
Language
Visuals

People emphasized that such an approach to measuring quality would take considerably more than the initially suggested timeframe. This led to the observation that it’s important to clarify from the start the extent of rigor expected in the evaluation.

Someone pointed out the difficulty of measuring the usefulness of documentation when you’re not the end user, stressing the importance of identifying the reader and the document’s purpose.

Ultimately, there was a consensus that the task was complex. For a more comprehensive and accurate approach, people advocated for ongoing content audits. Everyone acknowledged that evaluating documentation quality is a challenging but vital endeavor in maintaining effective knowledge bases.