• February 2017
    S M T W T F S
    « Sep    
  • Facebook

Implementing Swagger in your API documentation — My ISTC article

If you’re an ISTC member, then you already get the ISTC Communicator, and you can read my article in print or by logging into the ISTC site. You can view the table of contents for the Autumn 2016 here (but not the article content unless you log in as a member).

If you’re not an ISTC member, you can read my article here: Implementing Swagger (OpenAPI specification) with your REST API documentation, since I also published the article on my site in HTML format and integrated into my API doc course.

A lot of people ask about Swagger, and although I’ve written about Swagger previously, this is my clearest and most thorough article on the topic to date.

Recording of Let’s Tell a Story — Scenario-Based Documentation, by Matt Ness (STC Silicon Valley Presentation)

Presentation description

Here’s the description of Matt Ness’ presentation, “Let’s Tell a Story: Scenario-Based Documentation”:

To new users, complex software products can seem like dark woods on a stormy day. As tech writers, we often spend a lot of time talking about the overall shape of the forest and the variety of paths within it (conceptual docs), creating detailed catalogs of local tree species (reference docs), and providing step-by-step guides to things like “how to cross a river” or “how to knock on a door” (task-based docs).

But none of that helps your customers when they just want to know how to get to Grandmother’s house, without getting lost in the forest, falling into the river, and accidentally going to the other cabin in the woods, where the lycanthropic senior citizens live.

In other words, your customers need a narrative. And maybe they need lots of them. When you’re dealing with products that can be run and configured in a bewildering variety of ways, a single getting started manual might not do the trick. It’s like giving people a Choose Your Own Adventure book and only allowing them to choose one path through to the end.

For my talk I’ll explain how we became aware of the need for better scenario-based documentation, and how we ended up building a prototype during a hack week project. Now we’re on our way to creating a collection of short stories that show users how to string sets of features and procedures together to solve complex problems. We’ll cover some of the things we’ve learned along the way and offer best practices for those who want to tell a few stories of their own. (Read more details at STC Silicon Valley chapter)


You can watch a video of the recording here:


If you just want the audio, here it is:

Listen to this post:

You can download the MP3 file or subscribe in iTunes.


You can view the slides here:

Let's Tell A Story: Scenario-Based Documentation from Matt Ness

About Matt Ness

Matt Ness is a technical writer with over twenty years of experience at places like PeopleSoft, Oracle, and Intuit. He’s currently a writer for Splunk, a leader in the machine data analytics sector.

Balancing the never-ending list of documentation to write with your natural interests and passions

Listen to this post:

You can download the MP3 file or subscribe in iTunes.

Although most days are the same, they are a little different. My kids have returned to school, and so my summer routine of waking up “when I wake up” and riding my 8 miles to work along the scenic San Tomas Aquinas trail (which follows a half-dry canal) has changed a bit. I now ride my kids to school and then ride on to work. My two youngest (6 and 9) often glide along on roller skates while holding onto the back of a bike child carrier that I pull. My older two kids get themselves to school by bike and foot.

My wife is an early riser who leaves while it’s still dark and heads up to the “Dish” in Palo Alto to walk along a trail that is so popular, if you don’t get there before 7am, there is not a single place to park for what seems like miles.

The extra ride to school adds another 4 miles to my route, which puts my daily biking round trip at about 20 miles. When I also add in a few games of some post-work basketball, all the exercise can seriously wear me out. (Unfortunately, I still manage to eat enough calories to more than enough compensate for all the calories I’m burning.)

The fatigue from riding sometimes carries over into a sense of fatigue about endless documentation tasks. I’m still trying to follow Tim Ferris’ advice to focus on the highest two priority items first thing in the day and block out everything else.

Sadly, I’m lucky if I get one of the two items finished. Even if I do finish it, I usually can’t publish the documentation I write until I can get the right subject matter expert to review and sign off on the content – a process that can take anywhere from a few days to more than a week.

It would be more encouraging if I could see the to-do items decreasing little by little, but I think the reverse trend is happening. For every item I knock off my list, two more get added (both for tasks at work and at home). Sometimes I feel like I’m slowly sinking, and as much as I try to conquer the documentation mountain, it just keeps rising higher and higher in the sky.

I dream about a day when I’ll have marked every task as “Resolved,” like having reached a state of Inbox Zero. In this state, I’ll tackle incoming items with such a responsive velocity that those who requested the update would be surprised at how quickly I turned it around, like when you find that someone has responded to your email just seconds after you sent it.

It crossed my mind today that perhaps instead of writing documentation myself, the only way to truly scale and conquer this documentation mountain is to switch from author to curator. A marketer who works near me noted with glee how she already has four posts she is publishing on the company blog this week. Did you write them all yourself? I asked, ready to be impressed. No, she said, teams reached out to me with the content.

I’m not sure I would be entirely satisfied being a content curator instead of an author. Writing is my sweet spot, and where I perform my best (except for maybe setting up authoring tools). But no doubt a hybrid role of author/curator is essential to survive.

While the documentation tasks keep building, I’m also trying to build up my technical knowledge of Android and the products I write about. There’s a lot to building streaming media apps – it isn’t something one learns in a few weeks. What’s more, the developer audience is at such a higher technical level than I’m at, my documentation has to hit on the questions and gaps of knowledge they will run into, not just me. I just finished editing a document about 4K Ultra HD media that has so many details about refresh rates, color formats, codecs, and other specifications that I wonder if I’ll ever get to the point where I can consume this information as easy as reading a morning newspaper.

I try to get into work a bit early to push through some tech tutorials in the morning and at lunch, but taking time out of my mounting doc tasks to step through a tutorial is always a trade-off. Am I sharpening my ax, which will make it easier to chop down the tree? Or am I learning about something so disconnected to what I’m documenting that by the time the material becomes relevant, I will have already have forgotten it?

That’s the crux of ramping up on developer technologies – unless you’re immersed fully in the domain for an extended period of time, the info doesn’t entirely stick, and it slowly fades. Then months later you have a documentation task that requires the knowledge, but by then it’s only a dim memory.

One day I’ll be an Android master, and I’ll know these products inside and out. I’ll resolve all of my JIRA items, and I’ll find myself wandering up and down cubicle aisles chatting leisurely with colleagues because I literally have nothing to do since everything is done.

But that day is a long ways into the future, and I only have a vague idea of how it will be. It’s mostly a dream. I know that the longer I’m at a company, the more projects I work on, the more documentation I’ll become responsible for, and the less time I’ll have. If any bandwidth opens up, more projects will take hold of that bandwidth until it is maxed out. Maybe someday I’ll even have a “direct report,” which would require even more bandwidth.

Maybe it’s not the tech writer’s destiny to ever get a perfect handle on all the open doc tasks and master all the technology details. Maybe this state of slowly sinking but then somehow pulling myself up a bit each day is the permanent state of technical writing. Is this what makes the job interesting – the challenge, the steep learning, struggling against the insurmountable?

I reflected on this idea during several of my bike rides to work, in between listening to books on Audible. I’m currently listening to Ready Player One, by Ernest Cline. In the book, a brilliant video game designer (James Halliday) creates a virtual reality layer to every day life that becomes a new dimension that most of humanity interacts in. The earth has deteriorated, poverty has increased, and the only alternative to the dismal, gray, degenerate life on earth is the virtual world Halliday created, which he called the OASIS. (The book is set about 15 years into the future.)

In the OASIS, students attend school, interact with each other, and do pretty much everything that you would expect in a normal world – except that they do it by sitting in one spot wearing OASIS goggles, moving their haptic gloves (or haptic suits for those who have more money), and by manipulating their avatars. Their avatars can complete quests, collect magical items (which they put into their “inventories”), teleport from one location to another, explore different worlds, and so on. It’s a pretty engaging book with detailed and believable world-building.

One day the OASIS developer, Halliday, dies. He is enormously rich and with no heir. Who will he give the money to? He decides to create the ultimate game and award the prize to the first person who can find the hidden easter egg. This sets off a ton of adventures with our main protagonist, Wade, who learns everything he can about Halliday’s world – the video games he played, movies he watched, and other 1980s trivia from Halliday’s youth.

I’m only half way through the book, but I’m guessing that eventually Wade will win this game (or else team up with his cybercrush Ardemis and win it). But that’s sort of beside the point.

What is my point? Both Halliday, the brilliant video game creator, and Wade, the game-playing protagonist absorbed in Halliday’s video game and world lore, love what they do. Wade is engrossed in Hallidsay’s 80’s pop culture, video games, and life in the OASIS. It pulls him in fully and absorbs all of his attention. He loves video games and plays for the sake of the game.

Let me circle back to the mountain of documentation and other tasks. On the one hand, I could view this as a kind of endless list of to-do’s, the only really interesting thing being checking off the boxes beside the tasks. I’m not sure I can ever fully change my attitude to embrace the same zeal and drive that Halliday and Wade have with video games, but I am convinced that this element of fun, of obsession and interest and full absorption, is what drives one toward total mastery and ultimately brilliant feats of accomplishment.

The problem is that one’s natural inclination doesn’t always align with profitable outcomes. For example, Wade’s mastery of 1980s video games and life in the OASIS doesn’t do much for him financially except qualify him to work as a tech support agent at a company called Helpful Help Desk.

This past week I sort of let go of my goals and tried to get absorbed in my natural interests. You know what I ended up doing? Jekyll stuff. I refactored the Jekyll doc theme at my work to support translation, figured out how to drive a glossary and tooltips from a YAML file (across multiple languages), came up with a nifty technique for handling bookmark links from the sidebar navigation, integrated Bootstrap nav tabs into the UI, explored how other theme developers implemented breadrumbs, interacted a bit on the Jekyll talk forum about templates, and more.

If I wanted to put my mind to it, I could become more adept and skillful in creating documentation themes out of Jekyll. But as my wife reminds me, when you compare building this kind of knowledge against knowledge about Java, Android, or other programming languages, there’s a clear winner about which one has greater payoff. And that’s the dilemma for me. It is easy to get wrapped up a publishing tool, but developing content about technical issues developers face is the real payoff from a career standpoint. One day you could change jobs to a company that uses a different approach for authoring, and then all that tool knowledge would be wasted (most likely in the same way that learning Android would be irrelevant if you suddenly joined Apple).

I’m still in flux. I can develop a mediocre knowledge of developer tech, or I can go deeper with Jekyll, or maybe explore something else altogether, like web publishing in general. The web (not too unlike the OASIS) is the larger funnel for most of my activities. Regardless of the direction, all my activities seem to converge in building out my technical skills, which no doubt helps in any technical writing endeavor.

Other Stuff