Home »

Write the Docs Newsletter – September 2021¶

Hi everyone! Back from our summer break, it’s Beth and the newsletter team, bringing you our edition for September.

September already? I know, the year is flowing by. Autumn is slowly but surely arriving here in Europe; and while the weather may be cooling, at Write the Docs we’re warming up for our second virtual conference for the year. “Prague” is coming up on 3rd-5th October; our fabulous speakers have been announced, and ticket sales are still open. Hope to see you there!

Sadly, that will also be our last conference of the year: the Australia and India conference has been cancelled. Bearing in mind the immense stress of the past year and a half, we’re instead planning a smaller event to be more manageable for the organizing team. It’ll be in a meetup format, but with some of the great speakers planned for the conference - keep your eyes peeled for announcements there.

Avoiding the dreaded “wall of text”¶

The “wall of text” is a familiar conundrum for many documentarians, especially when a topic requires in-depth explanation. As writers and as readers ourselves, we want docs that provide sufficient detail and are skimmable at the same time. Here are some strategies that go beyond surface-level fixes to also add helpful context and support a better user experience:

Add thoughtful headings and subheadings to provide content signposts and help readers find information they might otherwise miss in a long span of text. Meaningful headings do more than just break up the text - they provide a mental picture of everything on the page and allow readers to focus on the pieces they really need to understand.
Use progressive disclosure, like linking to secondary pages for details or using expandable panels, to keep the entire text available without overwhelming readers at first glance. Learn more about progressive disclosure from this 2017 Write the Docs Portland talk, Building navigation for your doc site: 5 best practices, by Tom Johnson.
Rewrite long paragraphs to use lists. Condense the most critical points to eye-catching items in a list and make the text more skimmable. Write instructions in individually numbered steps.
Look for opportunities to use formatting to add meaning to the text. Use special icons or different background shading to delineate notes and warnings. Put code snippets, quotations, and math equations in their own indented blocks. Use bold font weight to make keywords stand out. Left-justify the first paragraph for each topic and block-indent subsequent paragraphs on the same topic.

Where are all the junior positions?¶

An interesting topic circulating in the WTD community is the scarcity of entry-level technical writing jobs. Nowadays, most employers seem to be looking for writers with at least five years of experience. But why is that the case? Perhaps because teams need the help of a seasoned writer to help them grow, but also because, in most situations, an experienced writer provides a greater return on investment than a junior writer. If a team is overloaded, they might feel unable to give someone less experienced the training, guidance, and mentorship they need.

So, how can junior writers find jobs when it feels like the odds are stacked against them? One suggestion is to pick a niche and dig into it. By becoming proficient in a specialized subject, new writers will be better equipped to compete in the job market - as other candidates for entry-level tech writing roles can be engineers or support engineers wanting to transfer into writing-oriented roles.

Another approach is to tap into your professional network. In a saturated industry, knowing someone who can help you get more experience on your resume can help hugely. After gaining some experience, seeking new positions becomes much easier - though that doesn’t mean it won’t be challenging still.

The best advice for those interested in tech writing, regardless of the industry, is to establish domain knowledge in a subject, leverage professional networks, create a portfolio of work, and explore opportunities that allow for continuous learning and skill building to achieve a fulfilling career. For more information on starting a tech writer career, check out this article on Career Explorer.

The basics you need to document an API¶

In a discussion this month around demystifying API documentation, we asked: what’s the minimum that you need to know to document an API? Here’s what the community thought:

What the user needs to know (just like any other documentation!). For APIs, that includes descriptions of all of the parameters, a sample request and response, as well as information about authenticating.
How to write and send cURL requests.
The principles of RESTful APIs, including the “verbs”: Create (POST), Read (GET), Update (PUT), and Delete (DELETE).
Most agreed that understanding the purpose of YAML and JSON is helpful; learning to read them is usually fairly straightforward.
Do you need to know the coding language used to create the API? Not necessarily. Having some programming knowledge is helpful, but if you have tools that can call endpoints and can give you reliable information for payloads and responses, you don’t need to know the language. Similarly, if you have great programmers that document the code, you may just need to understand the code’s structure well enough to find information.
What about the OpenAPI spec (formerly Swagger)? Not necessarily. It’s useful you want to define the API, but not necessary if you’re just helping the developers document it - you’ll mostly learn it along the way. (There are also a couple of other formats, like RAML.)
Finally, it’s helpful to have some understanding of how software communicates over HTTP: headers, errors, bodies. Some notions of computer security and performance - which isn’t too far away from pretending your day-to-day use of passwords and problems with connectivity issues. One handy tip - “imagine you’re a browser”!

Documenting hardware: different from software?¶

An inquiry about how hardware documentation might be different from software (or not!) produced a range of comparisons and stories. Spoiler alert: yes indeed it can be different, but “hardware” is a broad term! Contributors mentioned vertical farming equipment, hardware for biometric-based security systems, products for work safety and firefighting, heating appliances, and wind turbines.

One big challenge for everyone who described documenting hardware is the inability to test the product – either test it at all, test it readily, or test it in anything like a real-world scenario. Every hardware documentarian who replied noted their greater dependence on test teams, engineering, or technical support.

Some hardware products must be produced to exacting specifications, which can extend to the documentation, so depending on the product, doc reviews are more rigorous. PDFs and print manuals are much more common, and producing them to specification more exacting. Proofreading matters differently when fixing a mistake requires redoing print proofs! Plus, illustrations can matter more, to the point where one contributor likened themselves to a part-time art director.

Finally, there’s rarely any opportunity to gather customer feedback for the docs. Several folks missed the engagement with a developer audience their software docs work gave them, and the challenges of documenting new software features. They also acknowledged, though, that the challenge of setting up a doc system can be similar.

What we’re reading and learning¶

The #bipoc group’s been discussing the following materials on diversity, inclusion, and equity. Want to join the conversation? Please join us in the #bipoc Slack channel!

Two short reads: This article on TechBullion discusses the differences between diversity and inclusion in the workplace and why businesses need both. Many places lump these two terms together, but they are in fact two different things. And this article on WellRight expands on the topic of inclusion and discusses what it means to create a diverse and inclusive workplace. Hint, it goes beyond hiring.

A medium-length read: After the death of Daunte Wright, this post on HYPEBAE hosted a list of mental health resources for Black and other POCs. However, mental health isn’t a one-time need or a resource that should be overlooked; these resources are still available.