Write the Docs Newsletter – October 2023

Ave, documentarians. Halloween may be approaching, but there’s nothing scary about this month’s batch of stories from the world of Write the Docs.

The Write the Docs Documentarian Salary Survey for 2023 is open and accepting submissions! This is the survey’s fifth year and, in addition to our regular salary and job-related questions, we’re exploring our community’s thoughts on “back to the office” mandates, feelings about job security in a volatile market, and attitudes towards pay transparency.

So whether you’re an employee, contractor, freelancer, or currently unemployed, head on over and help us make this year’s survey the most useful yet.

In conference news, the in-person Australia conference has just announced its speakers. Check out the amazing talks you have to look forward to and then grab a ticket. If you’d like to apply for an opportunity grant, you have until 15 October.

The newsletter this month covers how to include links within your docs, whether you can show some of your personality in your docs, how to handle docs in the same repository as product source code, and how much (or little) to capitalize feature names. Hope you enjoy!

Personality in Technical Writing

There are still different views among documentarians on the issue of the importance of personality, customization, and tone in technical writing.

Some people said that strict accuracy was the most important consideration in technical writing, while others said that there was room for creativity and humor as long as precision wasn’t compromised. In particular, they said that adding a bit of personality can make such writing more interesting, especially if the readers can handle it.

Context also came up as an essential factor, with people agreeing that different kinds of technical material need different levels of formality. For example, troubleshooting guides should always be very clear, while onboarding tutorials might benefit from a more friendly tone.

Also, many people stressed the importance of knowing the audience and suggested that the amount of personalization should match what they want and expect. Some even pushed for tech writing that changes the language by using broader terms and more open methods to improve users’ experience.

Most people agreed that the audience’s needs should always come first. Individuality, personalization, and tone can improve technical writing in some situations, but isn’t appropriate everywhere. Finding the best mix between readability, accuracy, and interest is important for making technical documentation that users can relate to and use to reach their goals.

Docs with Code Or Just as Code?

Someone who switched jobs recently asked in #docs-as-code about the benefits and drawbacks of keeping docs in the same repository as app code. They moved from having docs in a separate repository to docs in the same repository as the product source code and were feeling frustrated.

Some of the perceived drawbacks to keeping docs with app code included changes feeling slower and less flexible, requiring PRs for everything, even small typos. Each change also required reviews from developers and lots of linting when app code wasn’t touched. Also, collaboration seemed more difficult than in tools like Google Docs and Notion. In short, it felt like there were roadblocks everywhere.

People noted some potential benefits, including increased accountability for changes with PRs. Some also felt safer knowing any mistakes weren’t theirs alone and that the CI checks and reviews helped keep entire pages from breaking. Someone also noted that with docs in the same repository as code, it was easier to enforce docs changes when code is updated, including potentially automating some changes.

People had some suggestions to help overcome some roadblocks. Opening PRs early in the process lets reviewers check out changes locally to see the effects. Someone also suggested using the principle of pair programming in pair reviews for easier collaboration: run the docs locally and walk through the changes on a video call. Another idea was keeping PRs small and therefore manageable, but batching really small things like typos together if each PR takes too long. And encouraging improvements to the CI to catch typos earlier and also only running when needed (not linting untouched code).

Either setup can work and each works for some situations. As someone pointed out, if you’re going to use docs-as-code, it’s best to optimize for the code tools and processes available to you.

Capitalizing Feature Names

How much is too much when it comes to capitalizing the names of features in the docs? The limit may be lower than you think! This month, most documentarians recommended using capitalization only sparingly in your documentation.

Unnecessary capitalization is distracting for readers. It looks odd in English, especially when the words aren’t proper nouns. Capitalizing generic terms like “dashboard” or “alert” makes it more difficult for readers to understand whether you’re talking about the general meaning of the word or a specialized concept.

In addition, many writing systems do not used mixed case, and capitalization norms vary among languages, so excessive capitalization can make it more difficult to translate your documentation. It’s also difficult to remove over-capitalization programmatically, particularly when certain words should retain capitalization in a specific context.

If you want to establish a precedent, it can be helpful to take a look at other companies’ docs. Also, capitalization and naming is often covered in style guides – check out these examples:

For a designer’s take on the subject, read Fighting Feature Names by Scott Kubie.

From Our Sponsor

This month’s newsletter is sponsored by Heretto:

At Heretto, we’re thrilled to unveil a game-changing feature for tech writers and developers alike: Interactive API Docs.

API Docs empowers companies to consolidate their product and API documentation into a single-source repository for a seamless user experience.

Unify your docs on one branded site, test APIs in seconds, and drive API adoptions with search-ready documentation.

Want to learn more? Meet with our team to see API Docs in action.


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

Events Coming Up