Blog Archives

What does Stack Overflow’s new documentation feature mean for tech writing?

Stack Overflow has recently announced the public beta release of its new documentation feature. That is, Stack Overflow now provides a platform for crowd-sourced documentation relating to any number of products, for the people, by the people.

For those of us managing the docs for widely-used products in particular, this means our customers may soon have access to an alternative, crowd-sourced documentation set.

What an awesome experiment for us as technical writers to follow! We’ll be able to see at first hand what our customers know they need, in terms of information about our products. Because this is Stack Overflow, the documented products are likely to be APIs, SDKs, and other developer-focused tools and technologies.

What if the documentation on Stack Overflow turns out to be voluminous and extremely useful – where would that leave us as technical writers working on proprietary doc sets? I think it will give us the opportunity to streamline our content, focusing even more than we do now on ensuring our information is up to date, and that our information architecture is the best we can make it.

In other words, we can ensure our target audiences can find what they need, even when they don’t know yet what that is.

Technical writing is hard. Information architecture is hard. The Q&A side of Stack Overflow works extremely well, because it focuses on short snippets of content that answer a particular question. It’s going to be very interesting indeed to see how well the new documentation feature works, with the more narrative demands of technical documentation.

An issue I foresee is that people will be tempted to kick off a topic, and then tire half way through and end up providing a link to the official documentation. Is that a bad thing? Tech writing know-how says our readers find it disconcerting to have to click around to find their information. It’s OK in a Q&A format, but not so good in a tutorial or step-by-step guide.

I really like Stack Overflow’s focus on sample-driven documentation!

I’d love to hear your thoughts on this development. Where do you think it’ll go within the next few months, and how about within the next two years? Will it fizzle into nothingness, or explode into something huge and beautiful? Will the original Q&A form of Stack Overflow merge into the new documentation form, becoming something new?

Doc bug fixits – a doc sprint to fix issues

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.

Friendly Purple Ant by Schade from openclipart.org

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.

Image attribution:
Friendly Purple Ant, by Schade,
from openclipart.org.

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.
  • Prizes.
  • How to participate.
  • A link to your fixit guide.
  • How to find you and other tech writers during the sprint.
  • Go!

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.

Write the Docs NA 2016 wrapup

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.

The sessions

These are the notes I took from some of the sessions I attended:

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.

write-the-docs-writing-day

Conference venue

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.

write-the-docs-ballroom

A closer view of the murals:

write-the-docs-murals

A chandelier:

write-the-docs-chandelier

More about Portland

My travelling bookmark, Mark Wordsworm, has some pictures and words about the city: Lost in Portland, Oregon.

Thanks

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!

A readable README file at Write the Docs NA 2016

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!

API documentation tools at Write the Docs NA 2016

This week I’m attending Write the Docs NA 2016. Today is a kind of pre-conference day. There are doc sprints, and an API docs meetup.

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.

Tools:

  • Docbox: An open source documentation tool for REST APIs. It’s a JavaScript application written in React (a JavaScript library for building user interfaces). It includes automated testing of the code samples in the docs. This looks like a pretty interesting collections of tools to explore.
  • retext-mapbox-standard: An open source tool that checks for grammatical consistency and correct spelling. This is implemented as tests, run against the documentation. It’s written in JavaScript.

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.

%d bloggers like this: