Write the Docs Newsletter – June 2024

Howdy, documentarians. Maybe it’s the ups and downs of the weather (from scorching hot to soaking wet), maybe it’s all the reports of AI coming for jobs, but it seems everything is in flux these days. It’s important to me to see the way documentarians support each other through these shifts. Maybe the only thing permanent these days is change. That and another monthly newsletter packed full of insights from our Slack community.

If you’re interested in what’s been happening recently in the community, check out the Q2 Community Board quarterly update. We also saw the first large gathering of the Write the Docs community in Kenya.

And coming up in the future, we have the Atlantic 2024 conference. Check out the speaker announcement to see the interesting talks that await you and be sure to grab a ticket.

This month’s newsletter offers ideas about how to demonstrate the value of what you do, tips on transitioning from working alone to being on a team, a resurrection of the old debate about using sentence or title case, and tips on optimizing the search on your docs website.

Demonstrate value from docs

How do documentarians justify their salaries (and promotions or salary increases)? Do individual documentarians perceive the value that their employers gain from their work? The value of documentation and your role in producing good documentation are actually wide-ranging. To justify your employment, you may have to quantify some aspects of your role.

Support

  • Assists users with setting up, learning, and troubleshooting a product. Saves support personnel from dealing with unnecessary support calls.
  • Contributes to the support team by helping support personnel do their work and eliminating duplicate work.

One resource for ideas about adding value to your documentation is Kathy Sierra’s book Badass: Making Users Awesome, which discusses helping your customers use your product.

Sales and marketing

  • Turns online browsing into actual sales. When evaluating competitive products, potential users can browse and make decisions based on publicly available documentation.
  • Helps drive sales by answering questions about features and how to use the product. This can lower customer acquisition cost.
  • Enhances branding and the company’s reputation. Consistent application of company style guides along with voice and tone presents a good face for the company.
  • Retains existing customers and reduces customer turnover.

Developers and engineers

  • Improves developer productivity. A GitHub Octoverse report from 2021 claimed good documentation boosts developer productivity by 50%. This may be particularly true when documenting APIs or SDKs.
  • Provides a different perspective. During SME interviews, when explaining the product and its features, engineers may discover design flaws, uncover unexpected edge cases, observe inefficiencies, and so on.

Company wide

  • Helps onboard new hires who need to learn about the company’s products.
  • Encourages existing employees to learn, relearn, or become experts in the company’s products.

For data about company-wide value and to access the Valuing Workplace Knowledge ebook, see Unshared knowledge costs money.

Transitioning from lone writer to a team

Joining a team of documentarians after working as a lone writer can be quite an adjustment. On the plus side, you may find that some of the pressure to justify your value is relieved by being part of a team that already understands what you do. Your new team is likely to have systems, processes, and tools already in place, so you only need to settle in and get to work. You’ll benefit from peer reviews and learning from your teammates, and it’s nice to brainstorm and prioritize with peers who have similar expertise – some said that they are better at experimenting, troubleshooting, and innovating when they’re part of a writing team.

At the same time, you’ll have to let go of some independence and share responsibility. You probably won’t get to choose the toolchain, and you’ll have to follow processes and style guides that reflect more than just your perspective. If the team is comfortable with the processes and tools they’re using, it can be difficult to make improvements even if something isn’t working well. You may not get every project you want when the work is distributed among several writers. You may be frustrated when quality differs among writers. Also, some writers on docs teams feel more exposed to layoffs since there are others on the team who do the same kind of work.

When you’re the new writer on a docs team after working solo, it’s important to be patient and assume good faith. Be kind to those with less seniority, take a servant-leader approach when needed, and try to remember that you have plenty to learn. For more tips based on this discussion, read Things I remind myself when working with others by Fabrizio Ferri Benedetti.

Title case vs. sentence case

The ongoing debate between title case and sentence case for headers, labels, and buttons in UI design is not just a theoretical discussion. It’s a practical consideration that directly affects the user experience. The key to a smart decision lies in consistency and accessibility, rather than the inherent superiority of one style over the other.

One person in a recent discussion emphasized the importance of consistency: “Pick one, stick it in your style guide, then ruthlessly follow whatever you decide.” Others echoed this, stressing the need for a documented and standardized approach.

Sentence case is often favored for simplicity and accessibility, especially for non-professional writers, which is a practical consideration in workplaces where technical writers are scarce. Another person argued against title case, highlighting the complexity: “Title case rules in English vary wildly.” Sentence case, being simpler, reduces editorial workload and aids translators.

On the other hand, some agreed on the value of title case for its potential to add clarity and emphasis. If the decisions are being made by professional writers, casing should not be too difficult. There are tools (such as Capitalize My Title) that can help even non-professionals adapt to a standard.

When choosing between title and sentence case, it’s crucial to consider audience needs and the context. As one member said, “It’s the job of the formatting and layout to clearly distinguish headings from body text.” This approach ensures that our design decisions are driven by user requirements.

The debate continues, but the main principle remains: choose a style, document it in your style guide, and apply it consistently. This approach enhances clarity and supports a seamless, accessible user experience.

Search platform tips for documentation websites

With Algolia/DocSearch holding a top spot among documentation search platforms, writers shared their alternative preferred search platforms in a recent community discussion. Popular alternate choices included Inkeep, Typesense, Meilisearch, Scroll Viewport, lunr.js, and Pagefind.

One writer detailed their approach to optimizing content with AI. They asked AI to list how human and non-human readers might misinterpret the content and describe what a user might be doing that led them to the document. Another contributor highlighted the efficiency of Pagefind while acknowledging the complexity of customizing its UI.

A key, unanimous takeaway was the critical role of well-maintained, clear, and current content in achieving effective search results. The discussion underscored the importance of ongoing content optimization and SEO to ensure users find relevant information quickly and accurately.

Additionally, accommodating various search terminologies, including outdated or industry-specific jargon, was seen as a way to improve the user search experience. However, the discussion suggested using balance, avoiding keyword stuffing, and using care when mixing terms in the documentation.

Accommodation strategies included pinning search terms to documentation and creating term aliases. With some platforms, such as Inkeep, to provide an answer for uncommon search terms, you can add a Q&A with the uncommon term in the question and provide an answer.

From our sponsor

This month’s newsletter is sponsored by Zoomin.


2024 Technical Content Benchmark Report

Measure your content performance against industry benchmarks

Zoomin’s 2024 Technical Content Benchmark report analyzes content interactions of over 97 million user sessions to provide a detailed overview of what good looks like in techcomm and the KPIs you should be looking at. Download the report to learn more about:

  • How your peers are faring in deflecting cases through documentation
  • The search KPIs you should be benchmarking
  • The data you need to measure content efficiency

Access the report here.


Interested in sponsoring the newsletter? Take a look at our sponsorship prospectus.

Events coming up