Blog Archives

Learnings from a doc sprint

A doc sprint is an event where technical writers work with engineers and other product team members to develop or update documentation. A well planned doc sprint is productive and rewarding for the documentation and the participants. This post shares some of the things I’ve learned from recent sprints.

A doc sprint can last anything from a few hours to a few days. I’ve found two days to be a useful period when the focus is fixing bugs. That may seem a little long, but it gives the disparate members of the team time to contribute to the sprint while keeping their primary roles ticking along too. When working with a distributed team across time zones, it’s particularly useful to have a flexible period that gives everyone the opportunity to take part.

Sometimes people use the term “doc fixit” when the sprint is focused on fixing bugs rather than developing documentation for a new product. Either way, a sprint or a fixit is a time box focused on the documentation.

Why run a doc sprint?

The primary goal is to fix documentation bugs and thus improve customers’ experience of the product. Sometimes it’s hard for a small team of technical writers to find the time to fix the small things. Yet, to our customers, those small doc bugs can mean death by a thousand cuts.

By inviting the developers and support or sales engineers to update the documentation, we make immediate and direct use of the expertise of our subject matter experts. By inviting product managers and programme managers to assess the documentation requests and help prioritise them before the sprint, we’re making use of their product and customer knowledge too.

Another goal is to foster a feeling of ownership of, pride in, and responsibility for the documentation amongst the engineers. It’s likely that they already know the value of the documentation, but they may not feel empowered to suggest and make updates. The hands-on experience of a doc sprint gives them that power. The feeling of power lasts long after the sprint has ended.

A doc sprint offers an opportunity for people to meet each other. Technical writers meet engineers and other members of the product team that we may not cross paths with often.

Some things I’ve learned from running doc sprints

These are a few things that have made an impression on me from recent sprints, and some hints that I’ve picked up along the way:

  • Engineers and other members of the product team appreciate the value of the documentation, and are keen to help improve it.
  • When deciding which tasks to allocate as suitable for the doc sprint, include some gnarly ones. It’s tempting, as a technical writer, to think that some tasks can be handled only by a technical writer. Well, that is true for some tasks:) but recently I’ve found it’s rewarding to err on the side of “let’s do it”. Big things happen in a doc sprint. Big bugs get squashed with surprisingly little fuss.
  • As the technical writer, be prepared to spend the entire period of the doc sprint reviewing changes, rather than making changes yourself. The main benefit of getting software engineers and support engineers to fix bugs is that you’re making direct use of their technical and business knowledge. They know the products and systems, and the ways the customers use them. On the other hand, the engineers don’t necessarily know the ins and outs of your documentation system. So, while the facts are probably right in the documentation created during the sprint, you’ll need to tweak the language and the adherence to other documentation standards like content re-use and page structure. It’s best to do that as part of the sprint, so the bugs can be closed off.
  • Create bug hot lists, to give people priority and focus. A hot list is a collection of bugs of a certain type. Since they’re fairly crucial to the success of a sprint, I’ve dedicated a separate section to hot lists below.
  • Hold a kickoff meeting at the start of the sprint, to give people information about what they’re doing and how to do it. Keep the kickoff short: 15 to 20 minutes is good. But allocate an hour, in case people have lots of questions.
  • Create a sprint guide that you can share with the sprint participants. The guide should be short and sweet, including information such as the date(s) of the sprint, the aims, the sprint organiser, the time of the kickoff meeting, the links to the bug hot lists, information on how to update the documentation, and where to send the reviews. Walk through the sprint guide at the kickoff meeting.
  • If you have the budget, provide food and prizes. For example, cakes at the kickoff, and prizes for most bugs fixed, most scary bug tackled, and so on.
  • Send out a report on how things are going at the end of the first day, as well as a wrapup after the sprint has ended. Include interesting bits of information such as who fixed the first bug, how many bugs have been fixed so far, and the scariest bug fixed.

More about hot lists

A hot list is a collection of bugs of a certain type. Many bug tracking systems offer a way of creating hot lists, naming them, and allocating bugs to them.

Hot lists are key to the success of a doc sprint where the focus is fixing bugs. When planning the sprint, I spend quite some time devising a set of hot lists that helps define the aims of the sprint, then filling the hot lists with issues. It’s worth it. When the day of the doc sprint dawns, people can get started immediately, even if I’m not there yet. (That last is particularly handy when my day starts five hours after many of the team members’ due to time zones.)

It’s fun to think up some attractive, appealing names for the hot lists. For example, being in Australia, we chose the name Mozzie (mosquito) for the hot list of small, easy fixes. For the big scary bugs, we chose Huntsman (a rather large, strangely beautiful, but admittedly scary, spider). In our most recent sprint, we created a hot list called Product Manager’s Choice (fix these bugs to win a PM’s mark of honour) and another called Technical Sales Engineer’s Choice (fix these bugs to win a TSE’s undying gratitude).

Note that a bug can appear in more than one hot list. For example, a big complex doc request could be a Huntsman as well as a Technical Sales Engineer’s Choice.

Have one master hot list for the sprint, which includes all bugs to be tackled during the sprint. This hot list will be invaluable in tallying up totals when the sprint is over. It’s also a good container for bugs that don’t fit into any of the other hot lists, but which you’d still like tackled during the sprint.

Having hot lists also makes it easier to award prizes based on the hot lists.

More about doc sprints

If you’d like to know more, try some earlier posts on planning and running a doc sprint. The sprints I’ve been involved in recently have focused on bug fixing. In earlier sprints we created entirely new documentation sets.

Bug husks

These are the husks of two cicadas that I spotted while walking in the bush. The bugs themselves have shed their skins and gone on to bigger, better things.

Cicada husks

3 essentials in an API get-started guide

Developers may need to hook their application up to an API so that the app can get data from somewhere, or share data with another app, or request a service such as displaying a message to the user. The getting-started guide is one of the most important parts of an API documentation set. Often the developer can find their way around an API with just the getting-started guide and the reference documentation.

A getting-started guide for an API (Application Programming Interface) helps a developer get their application interacting with the API.

At a minimum, a getting-started guide tells developers how to:

  1. Download any tools required, such as an SDK (Software Development Kit) or a code library.
  2. Get any necessary authentication credentials for their app, such as an API key.
  3. Fire up a hello world app. This is a program that does very little. Typically, it prints “hello world” to a web page, a screen, or the developer console. The purpose of a hello world app is to make sure the developer has all the tools and configuration required before they can start developing.

Here are some examples of API getting-started guides:

Interestingly, if you examine API documentation on the Web, you’ll come across a few different types of guides called “getting-started guides” or “quick-start guides”. It’s an overloaded doc type.:) For example, some quick-start guides take the form of a tutorial, leading developers through a simple use case for the API. The resulting app is something more than a hello world app, and is useful for developers who need information about what the API does (typical use cases) as well as the authentication and setup steps.

Seattle workshop on API Technical Writing

Will you be in Seattle on Friday, October 23rd? Join me and the Puget Sound Chapter of the STC for a full-day workshop on API technical writing. It’s free, and there’s free food too.:) Join me and other Google tech writers in a day of API doc lectures and hands-on sessions.

Anyone interested in learning about API technical writing is welcome to attend – you don’t need to be a member of the STC.

Quick links: Register to attend, and learn more on the STC Puget Sound site.

What is API technical writing?

API stands for Application Programming Interface. Developers use APIs to make apps that communicate with other apps and software/hardware components. API technical writers create documentation and other content that helps developers hook their apps up to someone else’s API.

For a tech writer, it’s an exciting, challenging and rewarding field. I love it!

This workshop gives you hands-on experience with APIs and API documentation, insight into the demands of the role, and plenty of information for your own follow-up study.

Workshop details

Date: Friday, October 23rd, 2015
Time: 9am to 4pm – breakfast and setup are at 9am, for a start at 9:30 sharp
Instructor: Sarah Maddox  – that’s me 😉
Cost: None. The workshop is given free of charge.
Location: Google Offices, 601 N 34th Street, Seattle, WA 98103. (Link on Google Maps.)

This is a practical course on API technical writing, consisting of lectures interspersed with hands-on sessions where you’ll apply what you’ve learned. The focus is on APIs themselves as well as on documentation, since we need to be able to understand and use a product before we can document it.

The workshop includes the following sessions:

  • Lecture: Introduction to APIs, including a demo of some REST and JavaScript APIs.
  • Hands-on: Play with a REST API.
  • Lecture: JavaScript essentials.
  • Hands-on: Play with a JavaScript API.
  • Lecture: The components of API documentation and other developer aids.
  • Hands-on: Generate reference documentation using Javadoc.
  • Lecture: Beyond Javadoc – other doc generation tools.
  • Lecture: Working with an engineering team

Preparation for the workshop

Please take a look at the prerequisites and setup to see what you need to install on your laptop before the workshop. Doing the recommended installations will save you a lot of time at the workshop so that you can avoid missing crucial bits when you’re there.

Meet Google tech writers

There’ll be some Google tech writers at the workshop, assisting with any difficulties during the hands-on sessions. I’m hoping a couple of them will present some of the lectures too.

Hope to see you there!

Here’s that signup link on Eventbrite. I hope to see you there!

Slide from lecture – working with an engineering team:

Working with an Engineering Team

Inspired by technical communication

What are the most inspiring, exciting areas of technical communication? I think this is a cool topic to explore. I’m hoping we have many different ideas and perspectives. Even better, I’m hoping that each of us thinks the area we’re personally working in is the most inspiring of all!

Why am I asking this question right now? Well, I do think it’s a very cool topic that will give us insight into the depth and breadth of our field. Also, I’m thinking of incorporating this topic into an upcoming presentation. If you’d like to add some thoughts via comments on this post, I’ll credit you with anything that I mention in the presentation.

To get the ball rolling, I’ll say that API technical writing is the best.:) It’s no secret that I love my role and talk about it non stop. Being so deeply immersed in APIs, I have the opportunity to play with them myself, build stuff with them, and show other people how they work. It’s a demanding, constantly challenging role – but that’s the way I like it.

It comes down to this:

APIs are the communication channel of the online world.
Developers need help hooking their apps up to someone else’s API.
Technical writers who can give that help are in a very good position.

Other inspiring or even revolutionary tech comm?

There are other areas of tech comm that seem equally appealing, at least from afar. How about documenting the software used by 3D animation specialists, or tools used by artists, or the games industry, or smart hardware, or the medical industry?

Perhaps there are tech writers working in areas that are revolutionary as well as inspiring. Here’s a challenge: top my description of API tech writing if you can.:)

An inspiring mushroom

I came across this Veiled Lady Mushroom while walking in the bush near Sydney, Australia:

Inspiring mushroom

Delete or remove?

What’s the difference between delete and remove? When should you use the word “delete” on a user interface or in a document, and when “remove”? Here’s an explanation that makes sense to me.

Use “delete” when you’re getting rid of the thing entirely – when it’s disappearing from the data store. Use “remove” when you’re subtracting it from a group or a list, but it remains available in the data store.

An example is the model of users and groups. Let’s say the user arthurdent belongs to two groups: spacers and earthlings. When Arthur no longer lives on planet Earth, you would remove arthurdent from the earthlings group. But if Arthur has departed the universe without leaving so much as a towel behind, you would delete the username arthurdent.

Here’s another example. Let’s say you have a number of credit card charges, which you’re adding to two expense reports. By mistake, you’ve added one of the charges to Expense Report 1 as well as Expense Report 2.  So you need to remove that charge from the report. In addition, there’s an erroneous credit card charge of zero dollars, which you can delete without adding it to a report.

Delete or remove

Works for me.:) What do you think?


Get every new post delivered to your Inbox.

Join 1,695 other followers

%d bloggers like this: