Home »

Write the Docs Newsletter – March 2023¶

Hello, everyone! March is here, which should mean the changing of the season. I hope you are able to find some balance with the upcoming equinox.

This month’s big community news is the announcement of the Portland conference speakers. This marks the return of in-person talks, and the variety of topics and speakers means it’s sure to be a treat for those able to attend. If you can’t make it to Portland, some other areas are also retuning to in-person meetups. So if that’s your thing, check out the list at the end of the newsletter.

Before the meetup list, enjoy some discussions about how to deal with being a sole documentarian, how to break up your docs-as-code, what the most interesting projects some of us have worked on, and how to face the challenge of documenting AI (since we know from last month that it won’t yet replace us).

Loneliness of the “Lone-ly” Documentarian¶

“Sometimes being surrounded by everyone is the loneliest because you’ll realize you have no one to turn to.” — Soraya

A recent discussion in #lone-writer elicited some responses with value for all documentarians. The essence of the posted question also appears in #career-advice: How to develop skills to feel successful throughout a career?

Some of the responses related to training opportunities: certification programs or online training (within the domain or for new skills). Some suggested joining the #learn-tech-writing channel and participating in its book club. For some people, reading books may be helpful.

The importance of developing relationships with other documentarians was brought up. Interacting with the Write the Docs community (asking questions in the Slack workspace, mingling in meetups, or attending WTD conferences) was important for many people. Maintaining relationships with previous co-workers or finding a mentor to bounce ideas off of was suggested by others.

Documentarians might have to step out of their comfort zone to ask for feedback. Some suggested developing relationships with “solid doc allies” or trusted subject matter experts within the company to get quality feedback. Learn from it but don’t take it personally. Realize that morale boosters are elusive for documentarians, so accept positive feedback gracefully.

Appreciate the benefits of being a lone (or lonely) writer. As the company’s advocate for your audience, you can ask for necessary information in a way to focus other teams. As long as the company considers documentation important, you have the power to make a difference and be recognized as an important contributor to your company.

Semantic Linefeeds¶

If you write the docs in a markup language such as Markdown, AsciiDoc, or reStructured Text, you might have encountered semantic linefeeds (also known as semantic line breaks). Semantic linefeeds mean that you add a line break after each sentence or even clause in your source file, not just after paragraphs. These shorter lines make the source files easier to read and edit (and the pages are still rendered in paragraphs when published).

Some documentarians dislike the choppy, random look that semantic linefeeds can produce. Others like the technique because it helps with docs-as-code issues such as keeping file comparisons (“diffs”) neat and legible and because it helps break down text for translation by line.

Among those who do use semantic linefeeds, the most common form is a variation called ventilated prose: one sentence per line. Adding a line break after every sentence feels somewhat natural and makes it easier to compare sentence lengths. Ventilated prose also makes it more obvious when you have long sentences that could be rewritten.

Most interesting projects¶

As the role of documentarians has become increasingly crucial in today’s fast-paced technological world, they have been tasked with numerous challenging projects. From documenting complex software systems to creating user manuals for cutting-edge devices, documentarians have a lot on their proverbial plates. However, among all these projects, some always stand out as particularly intriguing or memorable. For example, some recall documenting museum software to help guide staff in recording details about everything they collect, such as art, clothing, and dinosaur skeletons.

Others mentioned having a localization voiceover gig to demonstrate using a chainsaw, working on contracts for a company that built and sold childcare facilities, writing instructions for a reading tracking software company, authoring an operations manual for a robotic systems defense contractor, and creating content for a bespoke application for the oil and gas industry. From the variety of examples, it can be said that documentarians are tasked with complex and exciting projects, even if it’s just helping a parent write and edit books on sleight-of-hand magic.

The most interesting projects that documentarians have worked on showcase the diverse range of topics and industries they can adapt to and the complexity of the information they need to communicate. As technology continues to evolve and shape our world, documentarians will remain a crucial part of the process, ensuring that information is shared effectively and efficiently with a broad audience. It’s clear that it’s already a fascinating and challenging field, and it’s expected that more innovative and interesting projects will emerge in the future.

Documenting AI¶

Artificial intelligence (AI) is still top of mind for many. Based on a discussion this month, here’s what the community thinks we should we be looking out for.

First up, if you’re working on a machine learning (ML) tool, keep an eye on data lineage. It’s important to distinguish between the known input for the ML tool and These analysis or predictions that the tool outputs. For example, this might mean labelling a prediction on a person’s age as “Age analysis result” rather than “Age of subject”. If you’re interested, the following article present more on the subject: Always Leave An Analysis Paper Trail, and An Introduction to the Data Biography.

A related challenge can be explaining to end users what AI is actually doing. One discussion participant had been interested in the End-User-Centered Explainable AI Framework, a prototyping tool for explaining AI to users; another linked to an example of a documentation standard trying to be transparent about AI, IBM’s AI FactSheets 360.

The community was also interested in the ethics of AI. They recommended a few pieces: