If you’re a tech writer on a fairly typical large documentation suite, your docs probably contain some inaccuracies caused by error, misunderstanding, missing information, or pages going out of date. If you’re lucky, like me, you may have an eager group of developers, engineers, support team members, product managers, and more, who’d love to help fix those bugs. Enter the doc bug fixit, or doc fixit for short.
Over recent months I’ve run a number of doc fixits. It’s been a lot of fun, we’ve fixed some good bugs, and we’ve learned a lot. These tips may be useful to people considering running a fixit themselves.
A doc fixit is an event where technical writers work with engineers and other team members to update the documentation. It’s a type of doc sprint, but one where the aim is to apply small to medium-sized updates rather than add new features. The updates may fix errors in the docs or add missing bits.
Friendly Purple Ant, by Schade,
Why run a doc fixit?
These are some of the good things that tech writers experience from running a doc fixit:
- Fix bugs and improve the docs.
- Foster feelings of ownership of, pride in and responsibility for the docs amongst the engineers and other team members.
- Share your tech writing and information architecture knowledge with others, and see how appreciative they are of your skills.
- Educate people about the process of updating the docs, so they can do it themselves when they discover a small error in future. The process includes sending the doc to the tech writers for review and approval.
- Meet people in the engineering and product teams.
- Help the engineers see first hand how their code comments end up in the public-facing documentation (that is, the code comments that are formatted for Javadoc or some other doc generation tool, and thus appear in the generated reference docs).
How long should the fixit be?
A fixit can last anything from a few hours to a few days. I’ve found two days to be a good time period. It’s rare for each participant to be able to spend more than half a day on the sprint, and people are often called away unexpectedly to do their “day job”. A period of two days gives everyone a chance to help out, and ensures you get a good number of fixes done.
In particular if you’re working with teams in different time zones, the sprint should extend over at least two days so that people in far-flung offices get the best opportunity to work together on updates.
Things to consider before running a doc fixit
Some strategy never goes amiss:
- Consider whether your doc set will benefit from a fixit. Ideally, it should have a reasonably large number of bugs, and a fair number of engineers and other team members who can participate.
- Contact the tech leads and managers to explain the purpose of the fixit. Make sure they’re happy for members of their team to participate, and ask them to promote the fixit within their team.
- Select the participants based on their product knowledge. If people have already shown an interest in the docs, they’re an excellent choice. Send them personal invitations.
How can you encourage people to take part in the doc fixit?
Motivate the participants:
- Set a goal, such as the number of bugs to close.
- Suggest that people examine the docs and raise bugs beforehand, so they can fix them in the fixit. That’s a good way for them to get to know the docs, and a good way to put themselves in line for a prize.
- If possible, be present yourself at the location where most of the participants will be. It’s amazing and rewarding to see how engineers appreciate having a tech writer on tap.
- Make it competitive. For example, “that other team’s fixit closed 42 bugs – let’s beat that!”
- Provide food: pizzas, muffins, whatever your budget allows.
- Award prizes. It’s great to have a number of categories, such as the first bug fixed, the most bugs fixed, the most complex bug fixed, and so on. The prizes can be small – it’s the thought that counts. And the fun.
- Make sure people feel that the fixit is a well-organised event that will give them good material to add to their resumés.
Create one or more hot lists
Create “hot lists” of bugs that you want fixed. A hot list is a selection of items, in this case bug reports, with a characteristic in common.
For example, you could create the following hot lists:
- Quick, easy fixes.
- Complex bugs.
- Bugs that require specific technical knowledge.
- And so on.
Make sure the bugs in the hot lists are suitable for a fixit. For example:
- Ideally, the fix should be immediately relevant, and not dependent on a software release. That means people can submit the change and experience the immediate satisfaction of seeing it published during the sprint.
- The fix should not require too much tech writer input. So, structural doc changes, for example, are not suitable for a fixit.
- Take advantage of the fact that your subject matter experts are suddenly uniquely interested in the documentation. Choose tasks that require intimate knowledge of the product – where you’d have to consult your subject matter experts before you could make the update: corner cases, unexpected behaviour, and so on. In a fixit, it’s often your subject matter experts taking part!
- Prioritise small bugs that you’re not finding the time to tackle. An accumulation of small bugs can be as bad as a single huge one, for negatively affecting customer experience.
Supply a fixit guide
Keep it short and simple. Just one page is enough. Include:
- The goal of the fixit.
- Date and time.
- Location of the kickoff meeting.
- Links to the hot lists.
- A guide on how to update the docs.
- How to send the updates for review and approval.
- Your contact details.
Hold a fixit kickoff meeting
Put it on everyone’s calendars. Entice people with food.
Say just a few words, telling people about:
- The goal of the fixit.
- How to participate.
- A link to your fixit guide.
- How to find you and other tech writers during the sprint.
Run the sprint
Keep ’em at it:
- Issue daily progress reports: tell people the total number of bugs closed so far, the top runners for each prize, any other news items.
- Keep the food coming.
- Review the incoming doc updates promptly.
Wrap it up nicely
Remember, you’ll probably want to run another fixit. Wrap this one up well, so that you can refer to it in future.
Write a report and share it with everyone involved. Describe:
- Results (number of bugs closed).
- Participants and prize winners.
- Interesting factoids, such as something unexpected that happened, or the first product manager to fix a doc bug ever, …
Thank everyone involved, and don’t forget to hand out the prizes.
This week I attended Write the Docs NA 2016, which wrapped up a couple of hours ago. This post is a summary of impressions, with links to my notes on some of the sessions I attended.
One thing that strikes me about Write the Docs is that I’ve spent much of my time talking to people. This is partly because half of each day is devoted to unconference sessions as well as formal presentations. In the unconference sessions there’s a facilitator rather than a speaker, so everyone can contribute to the discussion. Another reason I’ve done so much talking to people is that there are so many interesting, friendly, enthusiastic people to talk to.
There were approximately 400 attendees. They’re people who love documentation – that is, people who know its value. Based on a show of hands at the introductory session, approximately 60% of the attendees are technical writers and about 15% are software developers. Others are UX specialists, support engineers, librarians, knowledge management specialists and more.
Another thing that strikes me is that the pre-conference activity was a half-day hike through the forested hills around Portland. Now, that’s my kind of activity.
These are the notes I took from some of the sessions I attended:
- Interactive document environments
- A readable README file
- API documentation tools
- Values of effective tech writing teams
- Internal docs for startups
- From tech writing to information experience team
For recordings of most of the talks, take a look at the Write the Docs 2016 YouTube channel. Here’s State of the Docs by Eric Holscher:
Doc sprints and API doc meetup
On the first day of Write the Docs, we gathered at Centrl Office to write docs and talk about API documentation. It was great chatting to so many enthusiastic, knowledgable writers. People got together and contributed to open source documentation with Mozilla, Google, and more. We filled three rooms to the brim. This photo shows the scene early in the day, before most people had arrived.
Days two and three were at the Crystal Ballroom. What a lovely venue! Here’s the view from the stage looking out across the conference attendees.
A closer view of the murals:
More about Portland
My travelling bookmark, Mark Wordsworm, has some pictures and words about the city: Lost in Portland, Oregon.
A huge thank you to the organisers of Write the Docs NA 2016. This is my first experience of a Write the Docs conference. I’ve wanted to attend for a couple of years, but it’s a long way from Sydney, Australia, to any of the conference venues. This year, everything came together and here I am. It was a great experience, and well worth the trip. Thanks!
This week I’m attending Write the Docs NA 2016. These are my notes on a session by Daniel Beck, titled “Write the readable README”. All credit goes to Daniel, any mistakes are my own.
Daniel Beck writes tech docs for developers and sys admins. A lot of his work is in deployment guides. In the course of his work, Daniel comes across many README files. In self defence, he decided to research README files, and looked at more than 200 of them. He analysed them from the following points of view:
- The type of project the README documents
- Other files accompanying the README file
- The markup used in the README
- The topics covered
- Links to other files and documents
- Images in the file: logos, other visual aspects
- What was good and effective
- What was bad or not helpful
- How did the README make him feel?
Daniel found that README files vary in quality. Some of them are even hostile to the reader. Some of them miss vital information, such as project name or location of the project. Some READMEs are very old – the oldest one dates from 1974! Typically, they’re Markdown files that contain a lot of information in visually unappealing form.
Tools like GitHub and Bitbucket have brought README files back to life.
The best READMEs give you confidence about a project. They help the reader identify and evaluate the project. They help you get started (use the project at least once) and engage with the project.
So, README files are useful, and are something we’ll probably need to create. Daniel cautioned us against relying too heavily on templates for README files, as a template may make you think that you’ve included everything you need even though there are some gaps.
Instead, Daniel has prepared a README checklist, available on GitHub. It’s a useful document, in that it suggests parts you may need in your README file, and also describes what to put in each part, tips on how to find the content for that part, and guidance on when you may need the part. Daniel also pointed out the template for contributing guides for open source projects.
Thanks Daniel for an entertaining and instructive talk, and for a useful checklist!
At the moment, I’m in the API docs meetup. The day starts with a few set talks, to be followed by “open space” sessions. Here are my notes on the first couple of talks about documentation tools.
Docbox and retext-mapbox-standard, from Mapbox
The first talk of the day was “REST API documentation generator” by Rafa of Mapbox. The Mapbox team writes the documentation in Markdown. In the background is Jekyll and GitHub pages. Rafa walked us through a couple of pages of the documentation, which includes code samples, generated for various programming languages, as well as hand-written words.
Rafa said this set of tools works really well for collaboration on writing the docs.
There was a lively discussion at Rafa’s session, with a very engaged audience. We discussed topics such as reader feedback, automated testing, size of the doc set, versioning, and more.
All this information was packed into half an hour! Thanks Rafa for a great session.
Tight coupling of API docs: YAML and custom tooling
The next session was “API documentation tooling at Capital One” by jennifer rondeau. Jennifer talked about the options and challenges for tight coupling of API documentation. Creating docs manually is not optimal. To keep your docs up to date, you need automated ways to sync your docs with your code. That’s what Jennifer means by “tight coupling”. In this talk, she’s focusing on the reference documentation, and specifically REST API reference docs.
You need to automate, but be ready for the areas where you need human intervention:
- Prefer a design-first rather than a code-first approach to creating an API. Jennifer’s team uses Swagger. For the most part, they use Swagger for naming conventions and exposing usable external APIs, not so much for the architectural considerations. Jennifer gave an example: Assume your development team creates a parameter that currently has only one permitted value. The parameter exists to allow for future expansion. In the external docs, remove the parameter.
- Note that Swagger YAML is human-readable, but not really. Jennifer emphasises that Swagger-UI is not a documentation tool. Swagger is most useful for generating server and client code. So, you need doc tooling. Jennifer’s team uses tooling that converts the Swagger YAML to a markup format (Markdown or HTML), and puts it all in a single file. Then there’s a manual step to clean up the text in the generated export files. You need to clean up the arrangement of the file, then expand descriptions and so on.
Jennifer walked us through the Capital One Platform documentation, and particularly the SwiftID webhooks, which is the output of the above processes. The hello world content is manually created. The source is all AsciiDoc, either generated from the YAML or hand-written. A member of the audience commented that it was good to see the manually-written content integrated with the generated docs.
Next, Jennifer discussed a different approach: creating documentation from tests. Jennifer talked about spring-restdocs, which adds the stubs for the documentation. You can then go and add the text later. How you automate your docs depends on how you’re building your API. The docs-from tests approach is useful particularly if you use the code first approach to creating an API. Your docs must exist in order for your tests to pass.
Thanks so much, Jennifer, for these tips on how to Swagger, and the hint about sprint-restdocs.
Are you interested in learning about APIs and API technical writing? Join us for a webinar, hosted by STC India. I’ll demo a couple of APIs and discuss the role of a technical writer in this area of the software industry. We’ll look at examples of API documentation, and discuss what type of documents an app developer expects when using an API.
The title of the webinar is “Introduction to API Technical Writing”. It’s intended for technical writers who know little about APIs (application programming interfaces) and want to explore the field of API technical writing. My hope is that, after attending this webinar, you’ll have the knowledge and tools you need to head off on your own explorations.
APIs (application programming interfaces) make it possible for applications to share information with each other. You could say that APIs are the communication channel of the online world. Developers need help hooking their application up to someone else’s APIs. We, as technical writers, give them that help.
Recording of the webinar [Update on 10 April 2016]: The recording of the webinar is now available on YouTube: Introduction to API Technical Writing.
Date and time: Friday 18 March 2016, at 1pm Indian time – that’s 6.30pm in Sydney. The session lasts one hour.
Who can join? Anyone. It’s free of charge, and you don’t need to be a member of the STC.
- An introduction to APIs.
- An overview of the role of API technical writer.
- Our audience – the developers who need our documentation to use APIs in their applications.
- The types of API we might be asked to document.
- Demos of 2 APIs that you can play with yourself.
- What API documentation consists of.
- Examples of good and popular API documentation.
- Working with engineers.
- Tips on getting started as an API technical writer.
Hope to “see” you at the webinar.