Home »

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!

Hyperlink Text¶

How to deal with links is a recurring question for documentarians. To answer it, some people suggested guidelines from the W3C, Microsoft, and Google.

The general consensus was to include text that’s relevant — not just ‘click here’. Suggestions included using the linked page’s title, turning the title into relevant text, and creating descriptive text based on the context. Non-writers (such as developers) may prefer using the title for simplicity. More experienced documentarians may want to craft the text.

There are several issues involved:

If there are inadequate guidelines for cross-referencing content, new or updated guidelines may be needed.
The page title may be too long or unhelpful. If so, either edit the title or summarize the content in a few words.
Some documentation systems focus on short, succinct topics. This may require many links to cross-reference content adequately.

A related issue concerns where to put the links: throughout the content or at the end of the content in a separate list? The main arguments against putting links at the end: the link may have lost its context or the reader may never scroll that far. In either case, it’s important to use relevant text. Having the link within the content may disrupt the reader by triggering cognitive overload and making them wonder: “Should I click or not? Should I click as I come to the link or wait until I finish reading?”

If you put links within the content, one reference suggested always putting the link at the end of the sentence to minimize distraction. Accessibility was an additional concern, but exact solutions were unclear because interpretation depends upon the screen reader.

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.