Author Archives: Sarah Maddox
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:
Are you in or near Australia in October and November? Then you’re in for a treat. We have two technical writing conferences in a row, within a stone’s throw of each other. Well, for some definition of “stone’s throw”, anyway. 😉
First up is the annual conference of the Australian Society for Technical Communication, which takes place in Surfers Paradise on 12-13 October. The conference theme is Let’s get technical, technical. Learn about CSS smart selectors, rethinking DITA, speeding up your web pages, blockchain, impossible docs, becoming an efficient writer, Simplified Technical English, and more. Follow up with a focused workshop on web coding. Check the list of presentations and fill in the registration form.
Next up is the Write the Docs AU conference in Melbourne on 15-16 November. This is the second WtD AU conference ever, following on from last year’s debut. This event offers a mix of presentations, lightning talks, workshops, and unconference sessions. Check out the schedule and get a ticket.
Found on a walk in the bush – patterns on the bottom of a squashed mushroom. Intriguing: