Sarah Maddox's Blog, page 9

Helping open-source contributors get started

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.

Doc fixits and content strategy at Write the Docs Sydney on Tuesday

The next Write the Docs meetup in Sydney is just around the corner:

#meetup_oembed .mu_clearfix:after { visibility: hidden; display: block; font-size: 0; content: " "; clear: both; height: 0; }* html #meetup_oembed .mu_clearfix, *:first-child+html #meetup_oembed .mu_clearfix { zoom: 1; }#meetup_oembed { background:#eee;border:1px solid #ccc;padding:10px;-moz-border-radius:3px;-webkit-border-radius:3px;border-radius:3px;margin:0; font-family: 'Helvetica Neue', Helvetica, Arial, sans-serif; font-size: 12px; }#meetup_oembed h3 { font-weight:normal; margin:0 0 10px; padding:0; line-height:26px; font-family:Georgia,Palatino,serif; font-size:24px }#meetup_oembed p { margin: 0 0 10px; padding:0; line-height:16px; }#meetup_oembed img { border:none; margin:0; padding:0; }#meetup_oembed a, #meetup_oembed a:visited, #meetup_oembed a:link { color: #1B76B3; text-decoration: none; cursor: hand; cursor: pointer; }#meetup_oembed a:hover { color: #1B76B3; text-decoration: underline; }#meetup_oembed a.mu_button { font-size:14px; -moz-border-radius:3px;-webkit-border-radius:3px;border-radius:3px;border:2px solid #A7241D;color:white!important;text-decoration:none;background-color: #CA3E47; background-image: -moz-linear-gradient(top, #ca3e47, #a8252e); background-image: -webkit-gradient(linear, left bottom, left top, color-stop(0, #a8252e), color-stop(1, #ca3e47));disvplay:inline-block;padding:5px 10px; }#meetup_oembed a.mu_button:hover { color: #fff!important; text-decoration: none; }#meetup_oembed .photo { width:50px; height:50px; overflow:hidden;background:#ccc;float:left;margin:0 5px 0 0;text-align:center;padding:1px; }#meetup_oembed .photo img { height:50px }#meetup_oembed .number { font-size:18px; }#meetup_oembed .thing { text-transform: uppercase; color: #555; }


Sydney: Content strategy and doc fixits

Tuesday, Jul 3, 2018, 6:00 PM

Atlassian
341 George St, Sydney NSW 2000 Sydney, AU

28 Documentarians Attending

Join us to chat about docs – why they’re a Good Thing and how to make them even better. Tech writers, engineers, editors, product managers, more – if you’re interested in docs, you’re welcome. —————— Presenter 1: Michalina Ziemba **Five steps to successful content strategy** In her talk, Michalina will share examples and practical tips …

Check out this Meetup →

What’s happening

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.

Login or log in, sign up or signup? How to tell when to use one word, when two

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.

[image error]

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:

[image error]

In the next slide – replace bbbbb with “back up”:

[image error]

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.

[image error]

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.

[image error]

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.

[image error]

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.

[image error]

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.

[image error]

[image error]

(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.)

Next Sydney Write the Docs meetup at Atlassian, July 3rd

We’ve just announced the next Write the Docs meetup in Sydney:

#meetup_oembed .mu_clearfix:after { visibility: hidden; display: block; font-size: 0; content: " "; clear: both; height: 0; }* html #meetup_oembed .mu_clearfix, *:first-child+html #meetup_oembed .mu_clearfix { zoom: 1; }#meetup_oembed { background:#eee;border:1px solid #ccc;padding:10px;-moz-border-radius:3px;-webkit-border-radius:3px;border-radius:3px;margin:0; font-family: 'Helvetica Neue', Helvetica, Arial, sans-serif; font-size: 12px; }#meetup_oembed h3 { font-weight:normal; margin:0 0 10px; padding:0; line-height:26px; font-family:Georgia,Palatino,serif; font-size:24px }#meetup_oembed p { margin: 0 0 10px; padding:0; line-height:16px; }#meetup_oembed img { border:none; margin:0; padding:0; }#meetup_oembed a, #meetup_oembed a:visited, #meetup_oembed a:link { color: #1B76B3; text-decoration: none; cursor: hand; cursor: pointer; }#meetup_oembed a:hover { color: #1B76B3; text-decoration: underline; }#meetup_oembed a.mu_button { font-size:14px; -moz-border-radius:3px;-webkit-border-radius:3px;border-radius:3px;border:2px solid #A7241D;color:white!important;text-decoration:none;background-color: #CA3E47; background-image: -moz-linear-gradient(top, #ca3e47, #a8252e); background-image: -webkit-gradient(linear, left bottom, left top, color-stop(0, #a8252e), color-stop(1, #ca3e47));disvplay:inline-block;padding:5px 10px; }#meetup_oembed a.mu_button:hover { color: #fff!important; text-decoration: none; }#meetup_oembed .photo { width:50px; height:50px; overflow:hidden;background:#ccc;float:left;margin:0 5px 0 0;text-align:center;padding:1px; }#meetup_oembed .photo img { height:50px }#meetup_oembed .number { font-size:18px; }#meetup_oembed .thing { text-transform: uppercase; color: #555; }


Sydney: Content strategy and more

Tuesday, Jul 3, 2018, 6:00 PM

Atlassian
341 George St, Sydney NSW 2000 Sydney, AU

3 Documentarians Attending

Join us to chat about docs – why they’re a Good Thing and how to make them even better. Tech writers, engineers, editors, product managers, more – if you’re interested in docs, you’re welcome. —————— Presenter 1: Michalina Ziemba Five steps to successful content strategy —————— More details and more presentations in the work…

Check out this Meetup →

What happens at the meetup

We currently have one speaker, Michalina, who will talk about five steps to successful content strategy.

There’ll be more speakers, and the opportunity to chat to old and new friends.

Who can attend?

If you’re interested in technical documentation, you’re welcome!

Date, time, and location

Tuesday 3 July 2018, at 6pm. We aim to finish around 7.30pm.

At the Atlassian offices, 341 George St, Sydney.

Want to air your ideas?

If you have an idea for a presentation or a lightning talk, let me know.

Thoughts on a remote Write the Docs meetup

On Wednesday this week, the Write the Docs (WtD) Australia group held a meetup entirely in cyberspace. Or, in the cloud, remote, virtual… whatever you’d like to call it.

How to build an Amazon Kindle book via HTML and OPF

I’ve recently published a couple of books in Kindle format on Amazon. The latest is Words Words Words: A Trilby Trench adventure. It took me a while to get the publication process to work, so I’ve jotted down my notes in case they’re useful to others.

Please be aware that these are just my own notes, and are not intended as any sort of official or fail-safe way of moving content to Amazon.

Overview of my writing and publication process

I write my books online in Google Docs. That means I can access the content from any computer at any time, no matter where in the world I happen to be, provided I’m online. Google Docs also has an offline capability, but I haven’t used it extensively.

For the conversion to Amazon Kindle format, I use straight HTML rather than a Word doc or other format. I convert the content from my Google Docs file to HTML, using a Chrome add-on: GD2md-html. Why use the add-on instead of Google Docs’s own export to HTML functionality? Because I want a single, simple HTML file that contains just the content with minimal markup.

Then I hand-craft the files for the table of contents and other metadata.

Here are my step-by-step notes, in the hope they’re useful to other people.

Step 1: Create an HTML file containing the content of your book (your-book.html)

My content is in Google Docs. This is the way I convert it to HTML:

In Google Docs, make sure all chapter titles are at heading level 2.
Convert the Google Docs content to HTML. I use the Chrome add-on  GD2md-html , with its default settings for the HTML conversion.
Save the result on your computer as an HTML file. Use any file name you like. For example, your-book.html.
Open the HTML file in your favourite text editor.
Make sure the character encoding in your editor is set to something other than UTF-8. See Amazon’s documentation. (I ran into trouble when uploading my files to Amazon because the apostrophes, ellipses, etc, were using the default character encoding for my editor, which was UTF-8. On the Mac, Latin-1 (ISO-8859-1) worked for me.)
Optional, for better HTML semantics: Change all em> to i>
Remove the heading level 1 element that contains the title of the doc: Remove this element containing your title
Add an HTML  and element containing your title. Example:


Put your title here


.
.
.




Add an HTML tag directly after the tag, as shown in the example above.
Scroll to the bottom of the doc, and add the closing and tags:



Change all the elements that contain your chapter titles, to include a page break element and an id attribute, like this:

Chapter 1

And:

Chapter 2

And so on.
Optional: Add a welcome blurb at the top of the page, before your first chapter. Something like this:
Welcome!

Welcome to Your book title, the crazy adventures
of a possum in a puddle.

Save the changes to your-book.html.

Here’s a minimalist sample for your-book.html:

Put your title here




Welcome!

Welcome to Your book title, the crazy adventures
of a possum in a puddle.

Chapter 1

Your content, including simple HTML markup such as italics.

Chapter 2

More content.

THE END

For more information, see Amazon’s guide to supported eBook formats.

Step 2: Create a table of contents file (toc.html)

Copy the example toc.html content below, and save it with file name toc.html, in the same directory as your HTML content file (your-book.html).
Edit the file in your favourite text editor.
In all the href attributes, change your-book.html to the name of your HTML content file.
In all the href attributes, change the chapter IDs and chapter names if necessary, to reflect the ones you’ve used in your HTML content file.
Add more list items to reflect all the chapters in your HTML content file.

Example of toc.html – unfortunately, I had to paste this as an image, because WordPress won’t let me include the HTML for this file. (I tried all sorts of things, escaping characters, using HTML entities, etc, but nothing worked for this particular set of code.)

[image error]

For information about the “landmarks” entry and other details, see Amazon’s guide to creating a table of contents.

Step 3: Create an OPF file (your-book.opf)

The Open Packaging Format (OPF) file is an XML file that contains metadata describing your book.

Copy the example OPF content below, and save it in the same directory as your HTML content file. The part of the file name must be the same as your HTML content file. So, if your content file is your-book.html then the OPF file must be your-book.opf.
Edit the file in your favourite editor.
Change “Your Title” to the title of your book.
Change “Your Name” to your name, such as “Sarah Maddox”.
Change “Name, Your” to your name with your last name first, such as “Maddox, Sarah”.
Change “your-book.html” to the file name of your HTML content file.

Example OPF file:

EN
Your Title
Your Name
Name, Your

For more information about OPF files, see the epub-boilerplate wiki on GitHub and the section titled “Finish your TOC” in the Amazon guide.

Step 4: Create a toc.ncx file – not sure this is needed

I’m not sure that you need a toc.ncx file for Amazon Kindle books. The Amazon docs seem to imply that you don’t need one. But I created one anyway, and included it in the upload of my book. I figure it may be useful for older types of devices that people may be using to read the book.

Below is an example of a toc.ncx file. Note the two attributes that increase incrementally: playOrder and the chapter number.

<!DOCTYPE ncx PUBLIC "-//NISO//DTD ncx 2005-1//EN"
"http://www.daisy.org/z3986/2005/ncx-2...













Your Title



Name, Your




Table of Contents



Welcome



Chapter 1



Chapter 2






Step 5: Zip all the files (your-book.zip)

Zip the following files into a zip file named something like your-book.zip (the name of the zip file is up to you):

your-book.html (the file name is up to you, but the extension must be .html)
toc.html (use this file name)
your-book.opf (the file name is up to you, but the extension must be .opf)
toc.ncx (use this file name)

Step 6: Upload the zip file to Amazon

Go to Kindle Direct Publishing. Sign in, or create an account if you don’t yet have one.
Follow the prompts to create a new ebook and supply the requested information.
When the Upload eBook manuscript option appears, click it.
Follow instructions to upload your zip file.

Troubleshooting

When things go wrong, the error message you get from KDP isn’t very helpful. It basically tells you that there was an error processing your file, and you should check your files.

A couple of issues I had, which may help you diagnose any problems you come across:

Check the little things, like syntax bugs a copy/paste errors. In the book’s content file, one of the id attributes for my chapter headings was wrong. In effect, I had two headings with id="chapter-2", and none with id="chapter-2". KDP was happy when processing the content file alone, but gave an error as soon as I tried to hook it up to the toc.
Character encoding is a hassle. I ran into trouble with apostrophes, ellipses, etc, because the default character encoding for my editor was UTF-8. It’s safest to set your editor to use ANSI. See Amazon’s documentation.

Hint: If things go wrong, try uploading just your HTML content file

If you can’t get your toc and OPF files to work, one trick is to first upload just your HTML content file to Amazon KDP, then download the resulting Kindle file from Amazon and adapt it.

Go to Kindle Direct Publishing (KDP). Sign in, or create an account if you don’t yet have one.
Follow the prompts to create a new ebook and supply the requested information.
When the Upload eBook manuscript option appears, click it.
Follow instructrions to upload your HTML file.

Amazon KDP takes your HTML and creates the basic set of files that it needs to make a Kindle book. You can now make use of those files. So, when the upload is finished, follow these steps to download the results as a zip file:

Still in KDP, scroll down to the Kinde eBook Preview section and click Preview on your Kindle device. A small section open on the page.
In the section that opens on the page, click the HTML link in the first bullet point. (The text is “Step 1: Download your converted book file: HTML or MOBI.)
Wait for the zip file to download, then unzip it on your computer.

Now you can continue working on the files as described earlier in this post, and upload them again as a zip file. You can download and upload as often as you need.

Other useful resources

Perry Garvin has written a useful article on making a Kindle book with HTML and CSS. I follow a different procedure from the one mentioned in that post, but the description of the files, and the sample doc set are very useful.

Amazon’s KDP Jumpstart is a good entry point into the world of Kindle Direct Publishing.

 

New Trilby Trench action novel – Words Words Words

I’m thrilled to announce the publication of the latest Trilby Trench action book, Words Words Words!

[image error]Trilby Trench’s worst nightmare comes true. Her friend Bonnie goes missing. The last message from Bonnie came from a remote location in Australia’s Top End. Since then, nothing. Has Bonnie simply gone walkabout, or has some mishap befallen her? It’s up to Trilby to find out.

There are times when words are evil. Times when words cause nothing but trouble and strife. That’s when you need someone who knows their way around a sentence and around a fight. Someone like Trilby Trench.

The complete book, Words Words Words, is available on Amazon as a Kindle ebook (USD $3.99) and as a paperback (USD $8.99).

Looking for a quick taste of the story? I’ll publish a few chapters on the Trilby Trench site. Chapter 1 is available now.

The Trilby Trench action adventures so far:

The first book in the Trilby Trench action series is A Word If You Please. It’s quite short – the length of a novella. It’s a great introduction to Trilby and friends. You can read the entire book here on the Trilby Trench site, as well as getting it in Kindle or paperback from Amazon.
The latest book, Words Words Words , is a full-length novel. The book contains around 67,000 words, and the paperback version is 361 pages.

If you’ve read either of the books and would like to add a book review on Amazon, that’d be awesome! Here’s my author’s page.

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.

Tips

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:

=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.
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.