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:
This app makes it easy for me to move GitHub issues from one repository to another within the same GitHub org. I’ve just used it for the first time. It’s a real time saver. And it’s pretty too, especially if you’re fond of ladybirds.
The Issue Mover for GitHub:
What problem does the app solve? Let’s say you belong to an organisation on GitHub with a number of repositories. The number of repos has grown over the months and years, as it inevitably does. As a result, you frequently find yourself needing to move issues from one repo to another. It’s time-consuming to do that by hand. You need to copy across all the content of and comments from each issue, reassign each issue to the relevant contributor, add back all the labels, and finally close the original issue with a note saying that it’s moved.
I’ve jotted down some example use cases. I’m pretty sure you’ll have others in mind too:
Docs: Let’s say, in the earlier days of your project people were adding the doc issues to the code repo. But now you have a website, with its own code and its own repo. So, you want to move the open doc issues from the code repo to the website repo. This is the situation I found myself in. The Issue Mover worked like a charm.
Community: At first, all your community-related requests were lumped together with doc issues. But now you have a large community that’s creating procedures and tools of its own. You create a shiny new community repo and you want to move the relevant issues into it.
Software components: Your app/framework is expanding rapidly, and it makes sense to split off separate code repos for some of the larger, less tightly-coupled components. Of course, the relevant issues should go along for the ride.
General and ongoing: People keep putting issues into the wrong repo! 😉 You like to keep things tidy, and want to move the issues to the logical place.
I was delighted to find this app, and I hope you find it useful too!
Disclaimer: Even though many of the contributors on the Issue Mover project work for Google (and so do I) this is not an official Google Product.
Open-source software (OSS) is a big thing, and becoming ever bigger. Open source gives people the opportunity to contribute to large-scale projects, and it gives those projects the opportunity to gather expertise from the community of experts rather than being limited to employees of any one organisation. The documentation in an open-source project is arguably as important as the software. But it’s often hard for would-be contributors to know where to get started. That’s true for people wanting to contribute to the docs as well as the software. Here’s where we tech writers can help!
One of the biggest hurdles I’ve found as a would-be contributor is that I need to figure out so many peripheral frameworks and tools before I can even think about contributing to the core software or doc that I’m aiming for.
Framework upon framework
I’ve had this experience a couple of times recently. To make one simple change, I need to learn three or four frameworks/languages/tools. In the docs world, these frameworks and tools include Markdown, Django, Read the Docs, Hugo, Netlify, GitHub Pages, and so on. And then there’s git and GitHub… you get the picture.
It’s not even as if you have to learn a framework for each new project. Often the frameworks are stacked on top of each other, and you have to know them all just to make a simple commit to a project. For example, for doc updates a fairly common set includes Markdown, Git, GitHub, Hugo, and Netlify.
Engineers have their own frameworks to learn. On the web side, these may include Angular, Node.js, React, and so on. In the world of containerisation, there’s Docker and Kubernetes. And so on. Wherever you look, you find multiple frameworks piling one on top of the other. These frameworks add flexibility and agility to the software systems, but they also add complexity to the stack of concepts people need to absorb and the tools people need to manipulate.
Tech writer speaking: who’s my audience?
In this world of proliferating frameworks, what can we assume our readers know? The readers in this case are engineers and others who want to contribute to an open-source project. That means they want to make a change in a repository, test that change, and submit it for approval. This is true for the docs too: If a change is anything more than trivial, contributors need to test or preview it before submitting a pull request.
I think we can assume our readers have indepth technical knowledge of one or more languages or tools, but it’s unlikely they have indepth knowledge (or even any knowledge) of all the tools they need to do the job. And so, they come to the docs for help.
Too often, people have to go read the entire Internet just so that they understand how to make a simple change in a project.
As tech writers, this is where we can shine
We can give these tech-savvy people the information they to get started, and point them to more in-depth guides when they need them.
In short, we can show people:
- The tools our particular project uses.
- A basic workflow for making a change, including step-by-step instructions for the minimal operation of each tool.
- Where they can find indepth information about each tool if they need it.
If you’ve recently made a change in an OSS project, or are planning to do so, jot down the steps you needed to take. They’re likely to be what everyone else needs to do too. If the project’s README file didn’t contain enough information to help you, submit a pull request that updates the README based on your experiences.
Even if you don’t have a particular change to make, take a look at the README or contributor’s guide for an OSS project that catches your eye. Does it tell you enough to get started? Would you be able to make a change to the contributor’s guide itself, by reading what’s in it? If not, consider updating the guide and using that experience to compile the steps as you go. It’s a great way to get some OSS contributions in your portfolio.
Examples of contributor guides / READMEs
These are a couple of OSS contributor guides I’ve updated recently:
- The Kubeflow website project on GitHub. (Scroll down to see the README, or open the README directly.) It’s edifying to read the comments on my pull request. I went down the wrong track not once but twice, due to lack of … documentation. 🙂
- The documentation contributors’ guide for SymbiFlow Project X-Ray.
- The Kubernetes project has a nice README. I like the way it starts with a welcome!
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.)