The art, and the power, of saying no

Recently, I needed to let a product team know that our tech writing team couldn’t take on the task of creating a particular doc. The doc was outside our normal area of responsibility, but one where we could certainly have added value. The problem was, we just didn’t have bandwidth. My manager showed me a published procedure which outlines our priorities. It was very useful to be able to refer the product team to the procedure, and to have at my disposal those words in the procedure which had been so carefully written for just this sort of situation. I was also able to offer the product manager our help in reviewing the doc once the engineering and product teams had created it.

This experience led me to think about the art, and the power, of saying no.

Saying no feels bad. You’re letting the side down. You and your team are underachieving.

Not so. I’ve come to the realisation that saying no is a good thing, provided it’s done under the right circumstances and in the right way. It’s good not only for you, but also for the people you say no to, for your manager, and for your team members. Even more, it’s good for the organisation as a whole.

How so?

When an organisation has had the luxury of a tech writer or two for a while, people start appreciating the skills we offer. They start asking us to create documents that are urgent, high profile, sales critical, and more, but that are sometimes outside our scope.

It’s fine to help out if the tech writing team has time. But often the team is fully taken up in other work that’s of equally high priority, and which is part of our primary responsibility. In such cases, it does the team and the organisation a disservice to say yes. Writers will end up working overtime, or the  docs under our primary care will suffer.

If we say no, people in the organisation may realise they need to hire more tech writers. In many cases they already know they need more writers, and our saying no can give them the data they need for their hiring requests.


If time allows, it’s good to be able to offer a little more than just a “no”. Here are a few ideas. Some of them involve preparation ahead of time, under the assumption that you’ll have to say no at some time:

  • Write up your team’s policy and responsibilities clearly, so you have somewhere to direct people to when they ask the impossible. Don’t be afraid to adjust the policy doc as time goes on, and as your team changes or you discover more situations which you can or cannot support. The team’s policy is not set in stone. It changes with your team, your stakeholders’ teams, and the organisation as a whole.
  • If you have a helpful suggestion or recommendation, include it when you say no. For example, point people to templates and style guides that will help them write the doc themselves. Look for existing documentation that may be similar to what they want.
  • If you have the bandwidth, offer to review the final draft after another team has created it and pushed it through initial review.
  • Encourage the product and engineering teams to contribute to the docs on an ongoing basis, so that they’ll feel able to write their own doc in this sort of situation. Create a quick-start guide to your doc tools and review procedures, and point them to that guide. On the topic of writing such a guide, you may find this post useful: the importance of audience.

Have you found yourself in a position where you’ve had to say no, even though you know that you and your team would add value to a task if you had bandwidth? I’d love to hear any tips you have on how to handle this sort of situation, and what you’ve learned from saying no.


The importance of audience, or, how to scale a tech writing team

A recent experience brought home to me how important it is to take account of the audience of a document. It also showed me how a well-tailored doc can help people perform tasks that they may need to do only rarely, but that are highly important when they do need doing.

Here’s the story, which you could entitle, The importance of audience, or, how to scale a tech writing team, or, how to encourage engineers to write documentation.

Over the last few weeks I’ve worked with a small tech writing team to create a documentation set for a product launch. It was a highly technical product where, by necessity, engineers wrote much of the material. In particular, we provided a number of tutorials that show customers how to run specific, optimised machine learning models, and we published best practices for people who want to customise the models.

In the leadup to the launch, new tutorials and updates were coming in thick and fast. Too many for a small tech writing team to handle. We needed the engineers to write the initial versions of the docs, and to send them to us for review and publication.

So, we needed a guide that would help the engineers write docs for our documentation site.

Now, of course, we already have plenty of guides for tech writers, telling new team members how to use the various editing and review tools. You’d be tempted to point the engineers at those guides and say,

“Go, do the same.”

That doesn’t work too well. The engineers tend to get lost in a sea of documentation that doesn’t answer their questions.

TL;DR: The audience is different.

  • New tech writers need to know how to use all the editing and review tools, as well as the tools for publishing a doc on the test site, and the processes for reviewing and publishing changes.
  • The engineers know most of the tools and processes already, since the docs are in the same repository as the code that the engineers work with every day. The editing tools and review tools are the same too. Even the source format (Markdown / HTML) is familiar. All the engineers need to know is:
    • Where to find the doc source, which is in the same repo as the rest of the code that they work with every day.
    • That the editing and review tools and processes are those they use every day too.
    • How to stage a doc on the testing site.
    • Who will do the doc review and publication.

To help the engineers get started quickly with writing docs, I patched together a very short guide containing the information outlined in the above four points.

The short guide also focused on command-line tools rather than GUI, whenever there was a choice. Most engineers prefer the command line, as it’s where they spend most of their time. Learning the peculiarities of a GUI for a task they’re not going to do every day is a waste of time.

The short guide worked a treat. We had plenty of high-quality material coming through the pipeline. The engineers and the tech writers worked together efficiently, fast, and happily. A very small team of tech writers was able to produce high-quality docs on time, and stakeholders were pleased with the result. I think the engineers had fun too.

Giving a specific doc to a specific audience works!

Of course, the trick is to find out who your audiences are, what they need, and which of them are worth the extra work of receiving a doc tailored specifically for them. Another post, anyone? 🙂


How to moderate data input into a spreadsheet

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:

"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.
  • Replace MY-SPREADSHEET-ID your own spreadsheet ID. This is the ID of the Google Sheets doc. The ID is a long string of numbers and letters.
  • Replace MY-DATA-ENTRY-SHEET-NAME with the name of your sheet 1. This is the sheet that accepts data entry via a form.
  • Replace the cell range B2:K2000 with the location of the columns and rows in sheet 1 containing your data.
  • Adjust the column number in Col20 to 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.

2018 conferences now open on Tech Comm on a Map

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:

  • Click the new ⊕ icon  on the web app.
  • Or select the Add event option in the menu in the Android app.

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.

Doc sprint at Write the Docs day Australia

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
  • webpack (JavaScript module bundler), led by Chris
  •, led by Geoff

What happened in the sprints

I ran the sprint on the Dart docs. Dart is a programming language with accompanying libraries. Developers use Dart to create apps that run in a web browser (Dart code compiles to JavaScript), servers and command-line applications, and mobile apps via the Flutter SDK.

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!

%d bloggers like this: