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:
The next Write the Docs meetup in Sydney is just around the corner:
We have two presentations lined up, preceded by pizza and chatting!
- Michalina will talk about five steps to successful content strategy.
- I’ll follow with a presentation on doc fixits: What is a doc fixit (hint: a way of fixing doc bugs en masse), why would you want one, and what can you do with it once you have it?
Date, time, and location
Tuesday 3 July 2018, at 6pm. We aim to finish around 7.45pm.
At the Atlassian offices, 341 George St, Sydney.
Would you like to join us?
If you’re interested in technical documentation, you’re welcome! Sign up at the meetup and we’ll see you there.
When should we use one word, when should we use two, for terms like “log in”, “sign up”, “back up”, and the like? This is a hot topic among technical writers, UX writers, and any designers who use text in their products.
The question is particularly relevant in the software industry, but it affects other product areas too. For example, a gym may invite customers to an exercise class with wording like this:
We promise you a great workout
Work out with your friends and colleagues
How can we tell whether we should use one word or two?
Even if we ourselves already know the difference, how can we teach other people, like the engineers, designers, product managers, and other people who work on our product interfaces and documentation?
A presentation – a bit of fun with a serious goal
I’ve put together a presentation that explains a way to help ourselves and others decide when to use one word, when to use two. It’s a bit of fun, but with a serious goal.
You can find the presentation on SlideShare: One word or two? How to teach the difference between “login” and “log in”, and other mind-bogglingly important compound words.
This blog post contains some extracts from the presentation.
The presentation shows a couple of slides containing a few sentences. Embedded in the sentences are some strings of repeated letters, like lllll or bbbbb.
To play along, you’ll need to replace the string of letters with the terms “log in” or “back up”.
Try speaking the sentences in your head., or even saying them out loud. This is where the bit comes in about your partner needing to be in a good mood: you could even ask your partner to play along with you!
In the first slide, replace llllllll with “log in”
Here’s the first slide with letters for replacement – replace each series of lllll with “log in”. Don’t write anything down – just say the sentences in your head or out loud:
In the next slide – replace bbbbb with “back up”:
What’s the outcome?
Did you notice any pattern in the way you pronounced the words “login” and “log in”?
If you’re like me, your stress pattern in the middle sentence is different from the first and third sentences.
In the middle sentence, we give equal emphasis to both parts of the phrase: log in.
In the first and third sentences, we give greater emphasis to the first part of the phrase: login.
The stress patterns are the same for backup.
In the middle sentence, we give equal emphasis to both parts of the phrase: back up; log in.
In the first and third sentences, we give greater emphasis to the first part of the phrase: backup; login.
And it’s the middle sentence that uses two words, while the first and third use one word.
So, you can use stress patterns to decide whether to use one word or two.
That’s one way of doing things, but what’s the theory behind it?
The rules are something like this:
- If the phrase is acting as a noun, use one word. This includes cases when the phrase is used to qualify another noun.
- If it’s a verb, use two words.
The presentation goes into more detail and includes some sources and additional reading.
What about hyphens?
Yes, what about hyphens. I think this is my favourite slide, because it shows a pic of a Tawny Frogmouth. They’re the coolest birds ever.
I’ll leave you to read the rest in the presentation itself
The complete presentation is on SlideShare: One word or two? How to teach the difference between “login” and “log in”, and other mind-bogglingly important compound words.
(Note: This presentation is a prettified and updated version of my earlier blog post, published in April 2014. There’s a spider in that one.)