Agile documentation customers

I continue the reflection I started in my last post, reviewing Scott Ambler’s article from 2002, Can Documentation Be Agile?

To no surprise, the customer emerged as being a critical element in Agile documentation. The points in Scott’s article refer to the Customer as though the customer is singular. Users, the user, etc. are also used similarly. In most cases, however, (i.e. with any luck) there is rarely only one customer. So, how can we understand all those people?

Find the center of mass

In physics, large bodies are modeled around a center of gravity or center of mass. This notion facilitates the study of very large objects, planet- or galaxy-sized objects in astrophysics, by modeling them as a single point with the mass of the entire object.

As with planets and galaxies, customers can also be modeled in a similar fashion. Many customers can be (and are frequently) modeled as a few personas or market segments. This is common in fields that deal with large numbers of people, such as marketing and advertising. In these cases populations are described by what they have in common and treated as a single persona. Does that mean every person in a segment’s population is the same? Of course not. But a well designed persona or segment describes the common attributes of the group sufficiently for its intended use. Just like knowing the location of an object’s center of mass will let you understand its properties and behaviors when acted upon by external forces.

One drawback to this method, is that when you miscalculate an object’s center of mass, it won’t behave as you expect it should. Its behavior will be consistent with its actual center of mass (whether you know where that is, or not). Where I’ve seen personas and segments go awry in technical writing is, inevitably, when they were not applied or not defined well.

Base personas on research

Just as an object’s center of mass is found through measurement, a population’s or segment’s properties are also determined through measurements and analysis (a.k.a. research).

If you want to treat a population as a single entity, you must measure it precisely.

But measuring customers is not easy. So what’s a writer to do?

Iterate

Successive approximation is a method for improving and refining a measurement and is an important part of Agile. Measure, test, observe, refine, repeat (or pick your favorite method for this). With this approach, you can continuously improve your customer model such that you can treat the customer as a single entity. There are several ways to accomplish successive approximation methods, but the key factor is that you assume that you must evaluate and iterate and that these aspects are baked into every process.

So, one of the first steps toward having agile documentation is having the ability to iterate (cheaply and quickly) and the ability to measure and understand your customers.

But, we all know that. Now, to figure out how to make that part of the process.

Agile documentation practices

Scott Ambler started an interesting conversation about agile documentation on LinkedIn  a short while ago. I visited Scott’s site, to see what else he had to say on the subject and I came across his article from 2002, Can Documentation Be Agile?

In his article, he lists 12 points that can help documentation be agile.   Scott’s article outlines a view of writing that I have not seen in practice in the 14 years since he wrote it. In my careers as a developer and a writer, I’ve seen bits and pieces of his list in practice to see how they might work together. I’ve also seen many obstacles that keep them from becoming more widespread. So in that context, I reflected on his points to imagine what such a world might look like.

I think it starts with us, the Writers, who need to look at the job from a new perspective.

Writers are more than “the scribes”

First, writers are not just “wordsmiths.”  While we take pride in our ability to craft great content, that’s not where we add value. Our value comes from what we craft, not simply that we craft. Likewise, software developers don’t add value just because they code, they add value because of what they code.

So, how do we know what to craft?

Focus on the customer

His first point is where writing really starts and ends—the writer’s audience and customer. Writers need to know their audience first hand. They need to walk in their shoes. More importantly, they need to make (or be granted) the time and resources to do this. Every writer? Yes, I think so, at least to some degree. Why? The longer a writer goes without walking in the customer’s shoes, the more assumptions creep in and take hold. It starts off slowly, but eventually, the writer’s view of the customer gets out of sync with the real customer. Markets change. Customers change, Products change. It’s a full time job keeping them all in sync, but it’s a necessary one.

Keep it simple, but not too simple

Of course, where that fine line falls is the source of constant debate. But, why is that such a debatable topic? I refer back to the previous point. If you know your customers, you know what they want. If you don’t, you make assumptions, and so the discussion becomes one of assumptions and not data. Hence, the contention.

Another aspect of this which provides a challenge to a writer is when one topic needs a lot of content to be “simple enough,” while another requires very little. The former looks lavish and the latter seems incomplete—until you use the, of course. But I’ve seen this unevenness be the topic of contentious discussions. Why? Because, audience data to the contrary was lacking.

All the more reason for writers to get out and meet their customers.

Looking back at 2015

Blog Posts - 2015

It’s hard to believe: a) it’s 2016 (and still, no flying cars…), and b) it’s been over three weeks since my last post. I don’t have much to say about flying cars (except that it’s probably better that we don’t have them, yet), but it’s a good time to reflect on my first year of blogging.

Looking back

In my vision statement, I set a few performance goals and the graph shows how I did, last year. Not bad. A few under-performing months, explained (and, perhaps, excused) by the other, higher priority things going on at the time. Finishing my Ph.D. in the first half of the year and, well, I took a break in December.

The table shows the statistical summary of my blogging performance for last year. While I had some ups and downs, I averaged more than 5 posts per month. I managed to keep the posts under 500 words, except for the first one of the year–before I set that word count as a goal.

Posts/Month Words/Post
Average 5.4 369.7
Max 11 510
Min 2 78
Std. Dev. 2.98 126.05

Not shown in the stats is the time it took to write each post–about an hour each. I know that because most of them were written as I rode the train to or from the office (usually to) and that ride is 55 minutes.

Also not shown in the stats is the “start to finish” ratio, or, what the cutting-room floor looks like. According to WordPress, I started 79 blog posts, last year, and published 66 for a completion ratio of 84%.  I don’t know if that’s good or bad–or if published/started is even the right metric. Looking back at some of those unpublished posts, I think the right way to look at that number is that I published 100% of the posts worth publishing.

Looking forward

I think, for the time being, I’ll stick with the goals I set last year. The 500 word/post goal was a good goal to enforce sticking to the point and keep the work manageable, but it also limits their value and utility. I’ll be pondering that goal to see about how to create more valuable content while not making the posts to onerous to produce (or read).

So, welcome 2016 and all that it will bring and (belated) Happy New Year.

Quorans like my hangar flying

quora_ga_mvI made it to the top-10 most viewed in General Aviation, this week.

While, like the most viewed writer in technical writing notice I got a few months ago, this wasn’t an intentional goal, but I think these notices represent what I like to talk and write about. It’s encouraging to know that they are also what people like to read.

For those who aren’t familiar:

  • Quoran is the term for someone who participates in Quora. I’m not sure if you have to submit content or if just reading it qualifies you for the label.
  • Hangar flying is the term for talking about flying, whether you’re doing so in an actual aircraft hangar or not.

Finding open-source projects that need documentation

writemeI’ve suggested in various venues that aspiring (and experienced) tech writers look into open-source projects to find projects they can use to build out their portfolio. In addition to making your portfolio a better place, working on civic-tech open-source projects has the extra advantage of helping to make the world a better place.

The follow-on question to this advice is, invariably, “how do I find projects that need documentation?”

Well from your lips to Twitter’s ears. I got this link to Code for America as a Christmas present in yesterday’s Twitter feed.

They describe how to query for civic-tech open-source projects that are looking for help. You can modify the search to specify keywords, such as documentation. Try it and see if you can find a project you could help.

Search for civic-tech open-source projects that need documentation

This is a live link, so the content will change, but as I write this, searching for documentation returned over 300 projects.

Maybe there’s some potential for a New Year’s resolution?

More Audience, Market, Product

In a recent post, I introduced the Audience, Market, and Product framework. Within this framework, it is possible to understand the characteristics of each that influence the documentation plan. During this investigation, you might learn more about each that can also help guide the product development and marketing, in fact, I would be surprised if you didn’t, but I’m going to constrain the scope of this analysis to documentation only.

The previous post described these components of the framework and here, I look at what you need to know about each one to design your documentation plan. In future posts, I’ll describe some of the ways to learn what you need to know about each component.

When reviewing the following points, keep in mind that these aspects can vary over time. For example, the documentation requirements will change as the audience becomes more familiar with the product or the product becomes more (or less) successful in the market. So, it’s important to consider these components as dynamic and not static.

Audience

In looking at the audience, you want to have a clear picture of who the readers are. How will they consume and apply information about the product? This is important to know in order to design the content in a way that they’ll find most useful and effective.

Market

In reviewing the market in which the product is offered, you want to understand the position of both the product and the company in the market. This is essential to develop the rhetorical approach of the documentation that will be most effective for the customer and for the company. For example, does the documentation need to help sell the product or would that tone be inappropriate and counterproductive?

Product

Finally, there’s the product and its aspects that influence documentation. Some of these aspects can be large and obvious, like key features and functionality, while others might appear to be subtle, yet still have considerable impact on the documentation. As with the other components, the ultimate goal of knowing this is to develop a clear picture of what the customer needs to be successful with the product and what the company needs to be successful.

What’s next

In the posts that follow, I’ll present some of the questions to ask in order to find out the what you need to know to design your documentation plan.

Videos in technical communication

WinDevVideoThe subject of videos frequently comes up in conversations about technical communication, even in when talking about API documentation. On the one hand, they can add some zing to your technical content (and what technical content can’t use a boost in the zing department). On the other hand, they can produce a negligible, or even negative, return on the cost they took to produce.

Video genres

To make this discussion more concrete, I consider these genres:

  • How-to videos
  • Can-do videos
  • Meet-me videos

How-to videos

These videos describe, and usually demonstrate, a task. Ideally, they describe the end-state (goal), beginning state (you and your problem), and the steps required to take the viewer from beginning to end.

The video on how to repair eyeglasses is still my favorite example of this genre.

Depending on the nature of the task, the viewers’ goals are often reading (viewing) to do now or a reading (viewing) to do a task later.

Can-do video

Many products, software and APIs included, have more features than meet the eye, or more applications than the viewer might realize. The line between promotional and educational can-do videos is fuzzy. While technically user education, they can seem promotional because they are promoting a capability of the product. The difference is in the tone and the call-to-action.

Until I produced a video about a Microsoft API, I didn’t think it was possible to make a compelling video about an API, especially one with no user interface. It turns out that it is possible. It just takes imagination (and a lot of effort).

The viewers’ goals for these videos is, invariably, reading (viewing) to do a task later, if only because they didn’t know they could do it before or during the video.

Meet-me videos

These are the videos in which a member of the product or development team provides a behind-the-scenes look of the product, its development, or its manufacture. When they provide information about the internal architecture and implementation that can be applied by the viewer, they can be interesting and educational.

There are many bad examples of this genre, which makes the stand out ones really stand out. The TED talk by Tony Fadell, is a great, meet-me video because in it, we learn more about him in a way that is very accessible (as in, you could do what I do, too).

The viewers’ goal for these videos is often reading (viewing) to learn, because, unlike how-to and can-do videos, it’s hard for the viewer to know, in advance, what the video will deliver in terms of knowledge or entertainment.

Which one to choose?

As always, it depends.  I think the Audience-product-market framework applies to videos as it does to any other type of content. If you understand what resonates with the audience and how to present that in the prevailing market, the best type of video for that situation should be clear. Understanding the readers’ goals, of course helps bring the answer into focus.

Audience, Market, Product

In a podcast-interview I did with Tom Johnson, I mentioned this framework as a way to evaluate technical documentation requirements. The components of audience, market, and product aren’t anything new, nor is considering them in documentation planning. What’s been missing, however, is an effective way to understand them in a way that informs documentation.

This framework is my latest iteration on how to apply the 12 cognitive dimensions of API usability to technical documentation. These dimensions, by themselves, are very difficult to apply for various reasons, but I think the notion of identifying the components and elements of an interaction can be useful—but the method must be usable. So, I’ve taken a step back from the level of detail the 12 dimensions to these three.

In this framework, it’s essential to consider, not just the documentation, but the entire customer experience in which the documentation will reside to correctly assess the requirements. I’m still thinking out loud because I think that there’s some value in lingering on the question(s) before diving into the solution process.

So to review the framework’s components…

Audience

These are the people who will (or who you expect to) read the content. Content includes anything you write for someone else to read. The boundaries of this depend on a lot of local variables, but should include all the content of the entire customer experience. Your audience might be segmented into groups such as  business/purchase decision makers, direct users, indirect users, support, development. You should know how they all interact with the entire customer experience.

Market

For this analysis, the market is the space in which your company or product is acquired. It could be an open-source product that offers a service or benefit similar to others. It could be downloaded from an app store. It could be something sold door-to-door. How your product appears in the space it shares with other similar products influences your content priorities. The more you know about the relationship between your product, its competitors, and its customers, the better you can assess those influences.

Product

Finally, there’s the product itself. How does it work? What does it do? How is it designed? What are its key features and benefits to the customer? What are its challenges? Knowing how the product’s features interact with the customer (i.e. audience) has a significant influence on the documentation.

And so…

And so, that’s where it begins. I’m still formulating the questions, and I think the questions are the key to bringing this down from a theoretical notion to something that can be applied by practitioners.

It all starts with knowledge (as opposed to assumption and conjecture) and that usually comes from research. With regard to research, I found these articles to be interesting:

Next, I’ll look at the questions that are specific to each component.

The post-hackathon hangover

Court-Whisperer-Screen-ShotHere it is, Wednesday, just four days after the hackathon and my post-hackathon hangover is finally abating. Don’t get me wrong, the hackathon was a great party. Like so many great parties, however, there’s often a morning after to get past.

Taking stock

I’ve already chronicled the experience sufficiently, so I’ll take a moment to indulge my post-hackathon hangover. This reminds me of my timer project. I’m seeing a pattern…

A demo is not a prototype

For as exciting as the hackathon was, the result was barely a protoype and, in all honesty, it was barely a demo. (It was a great pitch, though!) So, for all the accolades, there are a lot of problems that remain to be solved before the project is close to anything that could be deployed. Been there. Done that. Quite a few times, now.

That said (as the hangover fog begins to clear with the light of a new day…several days later), there were some valuable lessons to hang on to from the experience.

Less really is more

On top of our team’s focus and cooperation, I would attribute much of our success in the hackathon to our keeping the sample app and corresponding demo focused on their core values. Throughout the event, we explored various corners of additional features and context, which is good, but we also focused on the goal and used those explorations to shape the final product, not be included in the final product. Remember, the product of the hackathon is a pitch.

Less is more, until it’s less; and that’s the sweet spot.

I’m here to tell you that it is VERY DIFFICULT to throw stuff overboard to keep the ship afloat (one look into my garage will prove that point), but sinking due to an excess of good (and great) ideas, doesn’t help anyone (between you and me, building a larger garage doesn’t always help, either).

Keep your eye on the prize.

There’s a need

The positive reception to the idea we pitched shows that the idea has some legs. The audience immediately recognized the need as clear and they saw the value in the solution we presented.

The importance and significance of that  cannot be overstated. i.e.

Having a recognizable value IS HUGE!

There’s an opportunity

The post-hangover question to ask is, “how to realize the opportunity?” The solution will cost something. It’s not clear how much, though. The pitch and and overwhelmingly positive response from the audience surely will help appeal to and attract additional supporters, such as supporters, developers, designers, beta-testers, and the like. There might also be some interest in and market for a similar product in commercial applications. So..

What’s next?

That remains to be seen, but, for now, we have a website.

Some kinda fun.

My first hackathon experience

Hacking at the hackathonThis past weekend (Nov. 6-7, 2015), I attended the Seattle Social Justice Hackathon sponsored by the Seattle University Law School. I detailed my experience in a longer post, but here are the highlights.

The theme of the hackathon, making justice more accessible,  appealed to my latent activist persona (who doesn’t get out as much as he should), and I felt that bringing together a collection of designers, developers, lawyers, and social activists would, if nothing else, make for an interesting evening.

I wasn’t disappointed.

Our challenge

The problem I was drawn to was a way to help self-represented litigants (SRLs), a.k.a. pro se litigants. There’s a saying that, “A lawyer who represents him/herself has a fool for a client.” If that’s true for lawyers, what about someone with no legal training?  I know how difficult that situation is because I’ve been there, and done that. I would learn that my experience was not uncommon and that an estimated 36-million people become pro se litigants each year in the U.S. and they need help in many ways.

We formed a well-rounded team of six to tackle the problem: myself, the project owner/sponsor, a UX designer, and three developers. We dove into the problem and came up with a plausible technical solution in pretty short order, so the developers got started putting that together. As they worked, the sponsor, UX designer, and I started to understand the problem space in more detail.

The Court Whisperer is born

Our prize-winning app
Our prize-winning app

Normally, I wouldn’t recommend starting development before understanding the problem, but we understood enough of the problem and limited the scope of the technical solution to the part we understood well, so it worked out OK. Our understanding of the problem’s context evolved throughout the course of the event, hitting an abrupt pivot when a subject-matter expert (a law professor, no less) pointed out that an app that offered forms could be considered providing legal advice. Without missing a beat, we changed the context of our solution from an app that offers forms to an app that opens forms and then let the user enter data by speaking or typing it in while on their phone.

Fortunately, this didn’t alter the scope of the technical solution and so the developers barely noticed the change.

Dodging that bullet, we continued.I was the team’s PowerPoint wrangler and after several sessions with “pitch coaches,” I made a presentation with the fewest words ever (for me): Seven (with a vocabulary of only four). This event was a first in more ways than one.

We won first place!

Finishing the presentation, including the demo, with something like 57 seconds to spare, we impressed the audience with our story of how the Court Whisperer would help the estimated 36 million SRLs who interact with the courts each year in the U.S.

Apparently we also impressed the judges who gave our team first place and we’ll proceed with two other teams to another competition, next January.