Category Archives: technical writing
A smart engineer suggested a lightweight way of moderating data coming into a Google Sheets spreadsheet. I’m sharing it here in case you find it useful. Note that this is not an official Google solution, and anything on my blog is my own opinion or idea, not Google’s.
This idea came from François Wouts, as a lightweight way of moderating anonymous data coming into Tech Comm on a Map. The data source for Tech Comm on a Map is a Google Sheets spreadsheet. People contribute data entries anonymously from all over the world: conferences, meetups, educational courses, businesses. They enter the data via a web form or via an option in the Android app for Tech Comm on a Map.
It’d be a pity if something weird ended up on the map. I needed some way of moderating the incoming data before it ended up on the map.
The solution comprises two spreadsheets and a formula:
- The first sheet accepts the data entered via the form. Anonymous data comes into this sheet via the web form and the Android app.
- Also on sheet 1 is an extra column containing a value that indicates whether each entry is accepted or not. When entries come into the sheet, the column is empty. When moderating the data, I can mark each entry as accepted or not accepted by entering a value in that column
- The second sheet contains a formula that copies the data from sheet 1. It copies each row where the “accepted” column is set to yes, and ignores the other rows.
- Sheet 2 is protected from public editing. The app draws its data from this sheet.
Here’s the formula that copies the data from one sheet to the other:
=QUERY(ImportRange( "MY-SPREADSHEET-ID" ,
"MY-DATA-ENTRY-SHEET-NAME!B2:K2000" ) ,
"Select * Where Col20 = 'Y' " , 0)
If you’d like to use this technique, create a Google Sheets spreadsheet doc containing 2 sheets:
- Sheet 1 will contain the unmoderated data items. Any web form or app should write to this sheet.
- Sheet 2 is your protected data sheet. This is the sheet from which your app should draw its data. See the Google documentation for help on protecting a sheet.
Then apply the formula to your sheets as follows:
- Copy the above formula.
MY-SPREADSHEET-IDyour own spreadsheet ID. This is the ID of the Google Sheets doc. The ID is a long string of numbers and letters.
MY-DATA-ENTRY-SHEET-NAMEwith the name of your sheet 1. This is the sheet that accepts data entry via a form.
- Replace the cell range
B2:K2000with the location of the columns and rows in sheet 1 containing your data.
- Adjust the column number in
Col20to reflect the number of the column containing your “accepted yes/no” indicator.
- Paste the adjusted formula into the top left cell of sheet 2 in your spreadsheet. This is the protected sheet from which your app should draw its data.
I hope this is useful. I was delighted when François suggested it, because it’s lightweight and simple to implement.
The Tech Comm on a Map application now caters for 2018 conferences. This week I updated both the web app and the Android app to accept data for 2018. I also archived the 2016 conferences.
Tech Comm on a Map is an interactive map showing items of interest to technical communicators around the world: conferences, groups, businesses, societies, courses, and other things we find interesting. Tech Comm on a Map is available as a web app (see the previous link) and an Android app.
Highlights of the latest update:
- I’ve added a option, which you can click to add items to the map (new in the web app only; the Android app already has an Add event option in the menu).
- I’ve added a data type for 2018 conferences, and archived the 2016 conferences (web and Android).
Each coloured dot on the map represents a conference, business, society, group, course, or something else. Click a dot to see what it’s about.
Adding 2018 conferences and more
The map is now able to accept 2018 conferences, but there’s not much data on the map for 2018 yet. At this point I’ve added just two 2018 conferences. I’ll add more over the next few weeks.
If you have time, please do add items to the map: 2018 conferences, groups, societies, educational courses, and more. It’s also fun to add tidbits that you think are of interest to tech writers and have a geographical relevance. For example, the Other item type includes the birthplace of Ada Lovelace. Try de-selecting all event types except Other, and see what’s there now.
To add an item:
If you’d like to know more about the apps, how they work, and where the data comes from, take a look at the page about Tech Comm on a Map.
Yesterday was the very first full-day event held by Write the Docs Australia. In the morning we hosted a writing sprint, featuring five open source projects. The afternoon was devoted to five presentations. Of course, coffee and conversation happened throughout the day.
Although short, the writing sprint was fun and productive. Participants learned about open source, fixed doc bugs, discussed information architecture, and got to know some style guides.
At the start of the day, we invited people to pitch for their projects. Then each of the pitchers chose a table in the room. The other attendees decided which sprint to take part in, and joined the relevant table. These were the five sprints:
- Dart, led by Sarah Maddox
- Kubernetes, led by Jared Bhatti
- Cyrus (email), led by Nicola Nye
- ReactiveUI.net, led by Geoff
What happened in the sprints
We had four contributors taking part in the Dart sprint. Our focus was to update selected pages to match the Google style guide. We produced the following pull requests:
The Kubernetes sprint closed a number of issues, pretty much all those that had been allocated to the sprint!
At one of the tables, people spent much of their time discussing information architecture and doc design, using the open source project as the basis for the discussion. The project leader collected two pages of useful feedback as a result.
Things people learned
For many participants, the sprints were their first venture into the world of open source. A participant asked me, “So, after today, can I continue contributing to the docs? How would I do it?” She was pleased to hear that she could continue participating, and she’d do it in the same way as during the sprint. Our table also discussed contributing to open source projects in general: read the contributors’ guide for each project, be aware that pull requests do require work from the repository owners.
Participants needed a basic knowledge of Markdown. I gave a quick overview of the syntax, to get them started.
For the Dart sprint in particular, it was useful to learn a bit about the language. The sprinters’ guide included a quick introduction, and we ran a sample in Dartpad, to watch the code in action.
The open source projects we focused on are hosted on GitHub. Participants learned the GitHub workflow: how to edit files in a GitHub repo, submit a pull request (PR), receive feedback on the PR, make changes to the files in the PR, and re-submit the PR.
For the Dart sprint, our task was to update pages to follow the Google Developer Documentation Style Guide. One contributor was delighted to note that the style guide agrees with her tech writer intuition, overall. Another contributor reviewed a very long page, checking the style guide when in doubt. She found that, in most cases, the page did follow the style guidelines. I suggested that she add this information in the comment when she sent her pull request, as it would be useful information for the repo owners.
It was hard work
It’s hard work editing pages to follow a style guide. The Dart table stood out as being the quiet, focused area of the room. We were all deeply in the zone.
There came a touch of humour to dilute the hard work: a comment from one of the sprinters to Swapnil Ogale, Write the Docs organiser, after he’d been chatting with our table for a while.
Swapnil: “Good, OK, I’ll leave you to it.”
Sprinter, with a smile: “Yes, leave me alone. I’ve got a lot of work to do.” 🙂
Difficulties people encountered
People had trouble with the GitHub workflow at the start of the sprint. For example, when a sprinter first tried to enter a comment on an issue, an email verification request popped up. The experience was confusing.
Some people found it difficult to concentrate in the noisy environment of a sprint, and they felt stressed that they wouldn’t have time to achieve anything in the short time frame of the half-day sprint.
Three hours is a very short time for a doc sprint, particularly when the sprinters are new to the environment and the docs.
Feedback and thanks
If you were at the Write the Docs day, I’d love your comments and feedback on the writing sprints. I’m sure readers of this blog would be interested to know what you learned from the sprints. The owners of the open source repositories would like to know how they can make it easier for people to contribute to the doc sets.
A big thank you to everyone who took part in the writing day and contributed to the docs!
This week I attended the Technical Communicators Conference 2017, the annual conference of the Australian Society for Technical Communication (ASTC). This post is a summary of my impressions of the conference, with links to the posts I’ve written about each session.
I thoroughly enjoyed this conference, with its atmosphere of dedicated professionalism mixed with warm friendliness. The event took place in Sydney, Australia, filling two days with 14 technical sessions. By my rough estimate (I counted the tables at lunch) there were around 60 attendees. Most were from Melbourne and Sydney. A few people flew in from New Zealand, one from the west coast of Australia, and one from the US. Let me know if I’ve missed out any other travellers from far-flung places!
As is often the case with conferences, one of the best parts was meeting and talking to people face to face. Many were old friends whom I’ve met at other gatherings over the years. It was also great to make new friends.
A common theme arose in my conversations with the other writers. Those who have a role in a company or organisation find that there’s way to much work for them to handle. Even if they’re lucky enough to work with one or more other writers, there’s still a firehose of work pouring down on them. (This wasn’t so much the case with the writers who run their own businesses.) The people I spoke to said it was a good position to be in, yet at the same time they wished the organisations would allocate more budget and/or make more tech writing positions available. The writers feel strongly that they’re making a large contribution to the customer experience or process efficiency of their organisation, and could improve things even more if there were more writers around.
I think this sentiment is a very positive trend. Tech writers recognise their worth and feel that they’re doing valuable work. There was no frustration in the way people spoke. No-one said that their work went unrecognised within the organisation. They just wished there were more of them around.
The nice thing about a smallish conference is that you meet the same people more than once during the course of the two days, and can build up a relationship with them over that time. Most people attended all the sessions (there was only one track). People exchanged opinions enthusiastically during and after the sessions. During some sessions there were even jokes flying around between presenter and audience members.
Here are my posts about the sessions, in reverse chronological order, with the conference’s last session at the top of the list:
- Yes but I have my phone by Grant Mackenzie
- The vibe of XSL-T by Tony Self
- Writing micro-content by Margaret Hassall
- Documenting the tools you use by Swapnil Ogale
- The wonder of walkthroughs by Sonja McShane
- CSS Variables by Dave Gash
- Framework for evaluating communication by Neil James
- A tech writer, a map, and an app by Sarah Maddox (that’s me)
- Customising Microsoft Word by Rhonda Bracey
- Collaborating with developers by Dash Gash
- Get your words in order by Sonja McShane
- Bootstrap by Grant Noble
- Structuring content by Margaret Hassall
- Ten terms you thought you understood by Tony Self
Thank you so much to the ASTC committee and the conference organisers, for all the hard work you’ve put into this conference. It was excellent. Thanks also to the presenters who put so much time and energy into preparing and presenting the talks.
I’m attending the Technical Communicators Conference 2017, the annual conference of the Australian Society for Technical Communication (ASTC). This post is a live blog of a session at the conference. In other words, I’m writing as the presenter speaks. Any mistakes are mine, and all credit goes to the presenter.
Grant Mackenzie presented a session with the enticing title of Yes but I have my phone. I didn’t take any notes during this talk, as the conference organiser asked us to put away all pens and laptops. The point of the session was that you can do everything with a mobile device. I guess I could have taken notes on my phone, but somehow that seems to me like I’m paying less attention to the speaker than when I’m using my laptop. Something to do with the focus of attention and the posture required to take notes on a tiny screen. Entering text on a mobile screen also takes more time than typing, even though I’m an adept swiper. In fact, I’m writing this post on my mobile device, while on the bus on the way home from the conference. So, for me anyway, this is one use case when a laptop, or at least a keyboard, is better than a mobile screen.
Back to Grant’s presentation, which was lively and packed with information. The main thrust of the talk was that you can use a mobile device to create engaging, informative content. In particular, Grant demonstrated the use of various apps to create professional videos and photo-based art, complete with green screen effects and good audio.
Release notes came up again – they’ve been popular in this year’s conference. Grant’s approach is to have two important people in the company talk through the items in the release notes, while illustrating the features on screen, either behind the speakers by use of the green screen, or fullscreen using the speakers’ words as voice over.
We also saw some cat videos. 🙂
Thanks Grant. Your presentation was a thing of beauty.