Last week I attended Write the Docs Australia 2018 in Melbourne. Around 100 documentarians gathered to discuss words, code, style, and other essentials relating to technical documentation. There was plenty of food and fun too.
“What’s a documentarian,” you may be wondering? In Write the Docs parlance, a documentarian is someone who cares about documentation. Documentarians include technical writers and communicators, as you’d expect, but also UX writers, software engineers, marketing content writers, and more. If you think docs are a Good Thing, you’re in. 🙂
Approximately 100 people attended Write the Docs AU this year. Attendees came from Australia, the APAC region, and around the world. The following photo is from the Write the Docs photo set on Flickr:
Talks, workshops, and unconference sessions
The talks included:
- Lana Brindley: Facebook, Dynamite, Uber, Bombs, and You
- Mike Hamilton: Responsive Content – Presenting Your information On Any Device
- Kristine Sihto: The Art of Consistency – Creating an inhouse style guide
- Abhay Chokshi: UX writing – Let your product speak
- Alexandra Perkins: Making Yourself Redundant on Day One – Internal documentation to teach the next hire what you’ve learned
- Matthew Borden: Good Code, Bad Code & Code Review
- Nicola Nye: The subtle art of interrogation
- Daniel Stevens: Creating experiences with information!
- Laura Bailey: Backseat Content Strategy
- Mathew Patterson: Power up your support team to create better documentation
In addition to the presentations, we heard a number of informative, entertaining lightning talks. People could choose to attend one or more workshops and run or participate in a few thought-provoking unconference sessions.
These were the workshops:
- Sarah Maddox: Tech Writing 101
- Sara Marek: Let’s create a Style Guide!
- Jessica Parsons: Static Site Generators, What, Why and How
Tech Writing 101 workshop
Around 50 people attended the Tech Writing 101 workshop, which I ran with the able help of Eric Gilmore.
This tech writing stuff is hard. But fun!
Tech Writing 101 is a two-hour workshop on the principles and techniques of technical writing. It leads the participants through a series of pair-work exercises to improve the clarity, readability, and effectiveness of their writing. You can read more about the workshop on the Write the Docs AU page.
By the end of the session, participants also think differently about toothbrushes.
The workshop pre-reading is available in LisaFC’s GitHub repo. A number of the workshop attendees let me know that they plan to introduce that pre-reading to their colleagues, as it’s a great introduction to the patterns of clear writing.
Photos and videos
Tweets and write-ups
Have you written a report on the conference, or come across someone else’s writeup? Let me know by adding a comment to this page or tweeting @sarahmaddox!
My takeaway from the conference
So many people who’re passionate about docs! It was a privilege chatting to engineers, UX designers and writers, and marketing folks, as well as other technical communicators. Thanks to everyone for a great conference!
Hallo folks, I’ve decided to take down Tech Comm on a Map—this means I’ll remove the web page and unpublish the Android app. The web page will remain available until the end of November, to give people time to fix up any pages that are using it. The Android app will remain installed on your device if you’ve previously installed it, but it won’t be available for new installations.
Why am I taking them down? I don’t have bandwidth to look after them any more. The web app is suffering from a technical problem that I can’t fix, despite quite a bit of effort. On the Android side, I don’t currently use Android technology, and it therefore takes quite a bit of effort to get back into the swing of things each time I need to make a change to the app.
The usage stats for the apps are reasonable, but not huge. The web page gets a max of 50 visitors per day, measured over the last 6 months. There are 27 active installations of the Android app.
Thank you to everyone who has contributed data and code to this project! It’s been a rewarding experience developing the apps and working with contributors to the code and the data.
If my taking down the apps will cause you any trouble, please do let me know.
When someone asks you to create a quickstart guide, what do you envisage? More importantly, what does the requester envisage, and what do your readers expect from such a doc? Is a quickstart the same thing as a getting-started guide? Are you all starting on the same page? 😉
I’ve found that people mean different things when they talk about quickstart guides. Confusingly, people mean different things when they talk about getting-started guides too. For some people, quickstarts and getting-started guides are the same thing, but people differ about what that thing actually is. For other people, quickstarts and getting-started guides are separate docs with disparate goals.
As a result, when people get together to discuss the requirements for such a doc, the discussion can be long and complex. Debate may become quite heated. At that point, it’s a good idea to take a step back and check everyone’s initial assumptions.
I started this post with a number of questions. It may have felt like a barrage of questions! Actually, the crucial question is this:
“Who is the intended audience for the guide?”
Here’s an approach that appeals to me:
- A quickstart guide is for domain experts.
- A getting-started guide is for domain newbies.
Let’s take a look at how the approach pans out.
Quickstart is for experts
The quickstart is for readers who know the problem space and know exactly what they need to do.
As a user, I know what I need to do. Just show me how do it with your particular product.
These are domain experts. They know their field. Your product targets one or more tasks in that field. The experts have performed the tasks untold number of times, using various tools and processes. Now they just need to know how to drive your specific product to complete the task.
In the quickstart, they need to see:
- Where to find the product. This may be a web address, or a download link, or an address to a brick-and-mortar store.
- How to get any required access keys or authentication credentials.
- How to configure the product. For a developer-focused product, this usually involves creating a hello world application. For an end-user product, this may mean setting up a corporate or user profile and choosing other preferences.
- How to get started. This is often a walkthrough of a simple but common use case, which helps the reader learn the patterns of your product and map your terminology to theirs.
The domain experts don’t need the following information in a quick start guide (though they should have easy access to these items if they do need them):
- Detailed descriptions of the concepts relevant to the domain and the product.
- A detailed walkthrough of a complex use case.
- Explanations of why they’re performing each step.
Here’s an example of a quickstart guide for Google Compute Engine.
Getting-started guide is for newbies
The getting-started guide is for people new to both the problem space and the product.
As a user, I’m not sure exactly what I’m doing here. Help!
They need an introduction to the most important concepts, full context about each step they’re performing, and detailed setup instructions.
Typically the guide needs to assume some existing knowledge of the problem space. The writer needs to decide just how much prior knowledge to assume.
The guide to creating and starting a virtual machine on Compute Engine is a good example. It’s not titled as a getting-started guide, but I think it has the characteristics of one. It assumes the reader knows what a virtual machine is, but gives them plenty of context from that point onwards.
The marketing approach
I’ve had a number of interesting discussions with marketing teams about what should be in a quickstart or a getting-started guide. These discussions don’t generally distinguish between the two types of guide. The marketing approach views the document as an introduction to the values your product offers, why people should use it, and who else is using it.
The target audience is usually the business decision maker – the person who’ll decide whether to buy the product.
The product overview for Compute Engine is an example of such a doc.
What to do about these varying interpretations?
If people are coming to our docs with different expectations of what they’ll find in a quickstart or a getting-started guide, how can we ever hope to satisfy them all?
An ideal solution is to describe the purpose and intended audience at the top of the doc. Make it clear what people can expect before they commit to reading the doc.
That simple step may help prevent numerous complaints and negative ratings on our docs. Even better, it’ll help numerous readers know what to expect or at least send them away with a smile rather than a frown.
If people are coming to meetings with different expectations of the doc we’re building, how can we ever hope to get agreement?
A good solution is to make sure we’re all using the same terms and definitions at the start of the meeting. For example, the Compute Engine docs have clearly defined “product overview” and “quickstart” guides, and a getting-started guide in the “how-to guides” section. If people can agree on a breakdown of document types that suits the organisation, then everyone knows where to channel their energies. We’re all on the same page!
Best explanation ever
Here’s the best explanation I’ve seen of the purpose of a guide, from the Jupyter/IPython Notebook Quick Start Guide:
“Briefly, if someone gave you a notebook to run and you don’t know what a notebook is, this document is for you.”
And yes, Jupyter’s definition of a quick start guide differs from mine. Plus, they use two words for “quick start” instead of one. 😀
A few weeks ago I wrote a post about how technical writers can help open source contributors get started, and in so doing ramp up our own contributions to open source projects. A colleague has now pointed me to another great post on a related theme: Documentation as a gateway to open source, by James Turnbull.
My post focuses on the complexity of the open source world, which makes it difficult for anyone to get started, even to make a small fix to the source code or the docs. As technical writers, we can help people jump at least the initial hurdles. We can add docs that describe how to complete any relevant licence agreement, edit a code file or a doc page, send an update for review, and eventually submit the update to the repository. In documenting the process, we become our own test subjects, as we need to go through that very process in order to document it. Sound familiar? It’s what we do best.
James Turnbull’s post takes things further. He describes how to:
- Find a project that you can contribute to.
- Consider the etiquette of the open source community that you’ve chosen, before jumping in and making a contribution.
- Decide what type of edits to make. Both James and I describe READMEs as a good place to start. James goes on to examine strings, errors, and commands, and a few other file types too.
If you’re interested in open source, I recommend James’s post. It’s a good read.
Are you a software engineer wanting to learn the patterns of technical writing? Or a technical writer wanting to refresh the ABCs of our craft? Or someone who loves debating and exercising good writing styles? Join us for a Tech Writing 101 workshop in Melbourne, Australia, on Thursday, 15th November.
The workshop is part of the Write the Docs AU conference, and the cost of the workshop is included in the conference registration.
Workshop name: Tech Writing 101
Date & Time: Thursday, 15th November 2018, 2.30pm – 4.30pm
Prework and what to bring
Before attending the workshop, you need to do a small amount of pre-reading (about half an hour).
This is where you discover that tech writing patterns are interesting and fun.
On the day of the workshop, bring a laptop with a text editor and an internet (WiFi) connection to do the exercises.
The workshop leads you through a series of exercises to improve the clarity, readability, and effectiveness of your writing. You’ll work in pairs, learning from an experienced Google technical writer (me) and from each other.
Topics include the importance of knowing your audience; what can go wrong when you use passive voice; how to avoid getting tangled up in long sentences and disorganised paragraphs; how lists have taken over the world.
By the end of the session you’ll also think differently about toothbrushes.
During the workshop, you’ll apply the principles you’ve read in the prework. We’ve found this method of learning is highly effective. And it’s just plain fun. The workshop has been run at SREcon in Europe 2017 and at SREcon in the US in 2018, where it was very well received. People said they came away with useful skills and cleaner teeth.
The intended audience for the workshop is people who’re interested in learning how to write efficiently and effectively. That includes software developers, support engineers, UX specialists, product managers, technical writers, editors – well, really, everyone who needs to write technical content.
I hope to see you there!
Instead of a picture of a toothbrush (as that’d be a spoiler) here are some patterns from a recent walk in the bush: