Part 4: Test, Edit, And Publish Content
KEY TERMS
-
In this tutorial, an app represents a single piece of software that’s provided for others to use. This could be a mobile app, a web app, a microservice, a database, an API, a Figma component library, a React component library, a script, and so forth.
-
Any piece of writing that includes technical writing.
After completing Parts 1, 2, and 3 of this tutorial, your once blank page now has technical writing – you're officially in the home stretch! Technical writing on a page becomes technical documentation only after you test, edit, and publish the content.
Do not underestimate the exponential payoff that comes from testing and revising content. More than one technical writer can claim that revision has either uncovered bugs in software or improved it. But the process as a whole seems to be personal for most technical writers. Some like to preview their content and then revise. Others like to confer with peer reviewers right after a draft is complete.
The process that works for me is a cheeky acronym: A-TEAM. Because like the best novels out there, the best documentation is a collaboration. Writers have editors and publishers, technical writers have documentation stakeholders and peers.
Away from the content
Test the content
Edit the content
Approve the content
Merge the content
Away from the content
Before I make a single tiny edit, I put the content I’m working on a.w.a.y. Anywhere from three hours up to a day. Doing this helps me test the content with a fresh pair of eyes, so to speak.
Test the content
As an app user, I test the content to see if it meets the reader’s goal. This is the first thing I ensure because a revision is somewhat pointless if the documentation isn’t helpful to a user. Afterwards, I ask some key questions about the content. I’ve listed them in the cheat sheet for each content type.
Edit the content
Many writers – including technical writers – edit their content with the help of a style guide. You may be familiar with these since they’re specific to technology:
When it comes to editing, my flow looks something like this:
Choose or confirm a style guide. Some companies have multiple internal style guides. Squarespace uses the Google developer documentation style guide for internal technical documentation.
Make edits. The Highlights page in the Google style guide has a lovely, succinct list of what I need to be mindful as I edit. My favorite fangirl crush and former colleague, Eva Parish, has an article with a similar list, but in a narrative form.
Double check the code examples. They should be correct, concise, clear, and reusable. And if necessary, build on previous examples. Tom Johnson has a great informative article on code samples, and what makes them helpful.
Determine if the content is easy to understand. For proprietary content, I bribe ask a colleague who isn’t familiar with the content; for non-proprietary content, I use a readability¹ calculator.
Proofread the content. Most online word-processing apps don’t pick up typos like “there” versus “their”.
Approve the content
After the content has been tested and edited, I share it with reviewers so they can propose changes and approve it. Reviewers are often documentation stakeholders, and sometimes peers.
This part of the revision can be challenging because:
I love words.
There are too many “cooks in the kitchen” and no clear “chef”.
Virtual communication is funky. A long comment on a word or a phrase may not indicate how strongly someone feels about the topic.
Everyone believes that perfection is the goal.
So, I’ve learned to:
“Let it goooo… let it go!” #frozenforever
Pause, and ask for direction if discussions feel like an endless loop.
Suggest a quick face-to-face meeting or ask², “On a scale from 1 - 5, 1 being ‘I don’t care’, how strongly do you feel about this?”
Express what type of feedback I’m looking for. For example, “Homer, would you mind reviewing for clarity? Bart, would you mind reviewing for accuracy? Lisa, I’ll ask for approvals pending their feedback.”
Merge the content
In order to publish the approved content, I almost always have to merge it via a pull request (PR) which includes a Markdown file with the content. Once the PR is merged, a CI/CD process transforms the Markdown file to HTML then auto-publishes it to a platform. This could be Confluence, Backstage, or even a stand-alone site.
This process is known as docs-like-code³ (or docs-as-code).
You may be wondering why I didn't draft my content in a Markdown file to begin with. Well, like Tom Johnson, I find documentation reviews in GitHub “awkward and inefficient” ⁴. But you know what’s not inefficient? Converting text from a Google Doc to Markdown. Thankfully there’s a Google Docs Add-on that does it for you. 🕺
Try it out
Revise and publish your content using a process that works for you. Whether that’s the A-TEAM acronym or something similar. Some things to ensure and consider:
No matter which process you use, make sure you test, edit, and approve the content at the very least.
Some platforms have other methods to create, edit, and publish a page. For example, Confluence pages. In such cases, I’ve been able to copy/paste the content from Google Docs directly to the platform. But I may have to tweak the format and styles slightly.
Up next
Outro: What you did and what’s next. The outro recaps what you did – write technical documentation! – and introduces next steps like organizing a collection of documentation, revising existing content, and expanding your technical writing skills by joining the technical writing community. 💗
¹ See Wikipedia for a thorough definition and the different formulas used by readability calculators (aka readability checkers). Grammarly and Hemingway are popular ones, a simple search will retrieve many others. In general, the lower the readability score the better, but keep any tone suggested by a style guide in mind. For example, the Google style guide prescribes a “conversational and friendly” tone.
² Truth be told, asking someone “How strongly do you feel about this?” is a recent step in my process. Infinite thanks to Cap Watkins and his insightful well-titled article.
³ The succinct definition of docs-like-code at Write the Docs is my favorite, plus they provide a list of resources.
⁴ The review process is one of the limitations of docs-like-code that’s detailed on “I’d Rather be Writing”.
