Home »

Write the Docs Newsletter – April 2022¶

Hey everyone! It’s Beth and the newsletter team, back with another edition full of news and views from the docs world.

2022 is a big year for Write the Docs: it will be our 10th year of conferences in North America. To celebrate, we’ve added a video of an O’Reilly Interview of Eric and Marcia Riefer Johnston from 2015 to our “Origin Story” page. Watch and enjoy!

And if you fancy joining us for that 10th NA conference, you might like to know that we’ve just announced our fabulous speakers. Lots to get excited about there!

To finish, a bit of news from your editor. After four lovely years and 35 (!!) issues, it’s time for me to hand over stewardship of the newsletter to someone new. This is such a great opportunity to give back to the WTD community; so if you think it might be for you, take a look at our blog post about the role, Looking for a new newsletter editor and get in touch.

Where should support content live?¶

When it comes to making support content (like a knowledge base) discoverable and offering a consistent experience for users, what is the best approach? Should you keep support content with the rest of your documentation? Or should support content have its own separate site?

Some recommended keeping everything together, for example on the same platform. A single access point avoids authors working in silos, and helps to build a “single source of truth” - to avoid duplicated work or contradictory content. If you maintain support content as a documentarian, keeping it with the tech docs facilitates revising content to improve discoverability, rewriting unclear passages, and updating to match style guidelines.

Folks who leaned toward separation pointed out that support content and technical docs are very different and may not fit neatly into one information architecture. Tools for presenting support content can look more like news websites, with links to new and trending content, but without a hierarchical navigation structure for all available content. And if you want integrate support content into a ticketing platform to help users with issues, such platforms usually aren’t optimised for docs.

Others pointed out that support docs are often written by support engineers, writing speedy content in response to real help requests. If a tech writer doesn’t have time to edit everything, it’s an advantage to keep support content separate from more polished technical docs. Content that quickly solves a problem is valuable even if it isn’t perfectly written; it doesn’t make sense to delay publication until it can get writerly attention. For one more perspective, check out Product Documentation vs. Knowledge Base by Jakub Vul.

A final gem from the discussion was a rule of thumb for identifying what really belongs in support content:

Urgent (users need to know it now),
Recent (you just discovered it),
Niche (you helped one customer do it and someone else might want to do it too), or
Legacy (it’s good information about an older product or service with fewer and fewer users).

Breaking into tech writing¶

Breaking into tech writing and navigating the career transition can be challenging and stressful. Questions about which certifications and training to take, or what experience you need, don’t have clear-cut answers. Regardless, if you want to make the transition into tech writing, whether you’re coming from a different position or from college, here are some suggestions from our community:

Do your research on tech writing. Check exactly what type of work interests you and aligns with your career goals. The WTD topic archive has plenty of links to useful books, articles, videos, conference presentations, and podcasts.
Certification, training, and freelance opportunities are all valid ways to create a portfolio and gain a basic level of industry knowledge.
Leverage your experience even if you’re coming from a completely different field: there are often relevant skills you can highlight, like other kinds of writing, or research skills.
Contribute and engage in open-source communities to show your skills and passion.
Look for internship programs, for example through Outreachy, to find low-barrier entry opportunities.
Update your resume by adding new skills, linking your portfolio and social media, and tailoring your experience to each job posting.
Network with tech writers and find mentors to learn about new roles, share experiences, and develop professional relationships.
Lastly - don’t give up! These things take time and effort, but the community is here to support you - drop by in #career-advice if you need a boost.

Can form follow function in techdoc?¶

What matters more for documentation: “functional quality” (helps the reader get stuff done) or “structural quality” (looks nice, follows the style guide)? A lively discussion about which of two qualities matters more for documentation unsurprisingly produced the conclusion, “Why not both?” Along the way, however, folks contributed a plethora of refining points and important additions to the initial comparison. Here’s a summary:

It’s easier to think in terms of structural quality - grammar, word choice, appropriate headings, ease of scanning a page. It’s easier to check and to test, with linters and other automation tools.

But functional quality matters more. Do the docs achieve their goal of helping users get their work done? Testing this is harder - you can try by manually testing steps in docs, but that isn’t a full answer.

But when you dig into the details of functional characteristics, the distinction between functional and structural starts to blur. If all the information a user needs is available, but is so badly organised that the user can’t accomplish their goals, then functional quality is compromised by the lack of structural quality.

A refinement of this point distinguishes between the goals of the user – does the doc help the user accomplish their goals? – and the goals of the writer or the company they work for. If a doc helps the user, but fails a structural quality test, it might be costly or difficult to maintain, or might not integrate well with the rest of the docs. And these problems can become a failure of functional quality for the writer or larger doc set.

No surprise – it’s complicated! Binary questions like this can help start assessing doc quality, but use them with care.

What we’re reading¶

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!

TechRepublic discusses the Dice Equality in Tech Report and finds that both race and gender discrimination is still a problem in the tech industry.

Did you start a new job in the last two years? Fast Company explains that some of the “Great Resignation” is due to folks leaving their jobs for more diverse workplaces.

In the United States, should you say Black or African American? The Statesman talks with people about the difference and what they prefer..