Videos in technical communication

The 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.

November 20, 2015November 20, 2015

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:

The Secret Cost of Research was written about user and customer research, but applies to content
Seeing the Elephant: Defragmenting User Research provides a high-level view of research in practice

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

November 11, 2015November 15, 2015

The post-hackathon hangover

Here 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.

November 8, 2015November 8, 2015

My first hackathon experience

This 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

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.

November 4, 2015November 8, 2015

Projects that go as planned make for boring stories

My projects are rarely as exciting as this so, where's the story? — My projects are rarely as exciting as this so, where’s the story?

I was pondering my last reflection, this blog, and my, still imaginary, portfolio and found a recurring theme: they lack is a compelling story. I thought about the elements of a good story arc and words like struggle, challenge, and conflict and resolution came to mind.

But, what happens when things go according to plan? A worthy accomplishment, but a boring story.

Consider:

We started our trip in spite of the questionable weather forecast, but we were determined to arrive at our destination in time for my mother’s birthday celebration. The weather turned out to be worse that expected and going over the pass, our car slid into a ditch–reminding me that I should have replaced the worn tires sooner. Unable to get a cell phone signal, we shivered on the side of the road as we waited for a passing motorist to stop and help us out. Finally, a helpful soul gave us a ride to the next town where we were able to get a hot cup of coffee and hire a tow truck. As luck would have it, our good Samaritan was going to the same town as my mother’s party and gave us a lift. We arrived just in time to wish her a happy birthday and share in the cake.

Compared to:

We saw that the weather looked bad going over the pass, so we put the snow tires on the car before we left for my mother’s birthday party. The weather turned out to be worse than forecast going over the pass so traffic was slow. The cars in the ditch alongside the road and their attendant tow trucks didn’t help. But, slow and steady wins the race. We got to the party a bit later than we’d hoped, but with plenty of time to meet some long-lost relatives and to sing “Happy Birthday!”

I about fell asleep writing the 2nd version. Beyond a beginning, middle, and an end, it had none of the elements of a good story. No conflict. No drama. No tension.

Just predictable results.

As I reflected on the adapter box, I really couldn’t find much drama to add to the reflection. The most tense moment that occurred during the project was when I was afraid I might damage the case. As a result, I took precautions like measure carefully, tape over the box to protect the finish, and…

…wait for it…

I didn’t damage it. It all worked out fine.

Zzzzzzzzzz.

Which leaves me struggling between looking for stories like this flying story I posted in Quora, which have punctuated my life, and describing projects I’ve worked on–most of which are like the second story example above.

I suppose if I was a better writer, I could make the second version sound a little more compelling…

Maybe that’s the hidden opportunity in all this? Something to work on.

November 2, 2015November 3, 2015

Aircraft headset adapter – reflection

The finished adapter in service. — The finished adapter in service

Reflecting on my adapter project, I can’t help but compare it with the timer project–even if that’s not fair on many levels,

The project went pretty much as I expected. The circuit was simple and tested. There weren’t many known unknowns, but there are always the unknown unknowns.

On top of all this, I started the adapter project with a few more years of experience than I started the timer project.

It’s amazing how far in advance you can see the problems when you know what you’re looking for.

Unknown unknowns

They are what keep things interesting. In this case, it was the white Cat-5 Ethernet cable I used to connect to the radio. This cable has the double advantage of being inexpensive and having the connector attached. It has eight conductors arranged as four twisted pairs. The catch is the pairs make sense for the signals they are designed to carry, not my application. Bottom line, they pairs are not connected in a 1,2,3, 4… order, but as 3,4,5,6,1,8,2,7. Not the order I expected (even after researching the cable).

Measure twice, cut once, is how the carpenter’s saying goes. For this project it might have been better phrased, Measure twice, cut once, and then test two or three times.

Fortunately, no harm came to the project or the radio to which I connected and tested it (i.e. I was very lucky).

The biggest challenge was in the mechanical design, not the electrical design. I spent most of the time finding components and fitting them into as small of a box that I could. Arranging the components on the circuit board to line up the microphone-level adjustment potentiometer beneath the headphone jack was another mechanical challenge. Doing all this before drilling holes in the rather expensive ($17) case was another challenge.

Unfair comparisons

How did this project compare to the timer project?

Complexity: This had far fewer components and a much simpler function than the timer.
Tools: This project was designed and tested on the computer and built on tried and tested circuits whereas the timer was built and the components were fitted without any computer assistance.
Information: I was able to obtain electrical and mechanical information online to support the computer testing and design for this project and while this information was also available for the components used in the timer, it had to be applied manually (i.e. copied from a book).
Experience: Like I said, this wasn’t really a fair comparison. This was built with the help of many years of project experience.
Tooling: In this case, the comparison is actually fair in that both projects were fabricated with simple hand tools. It would have been nice to make a printed circuit board, make the holes with a drill press, and use something besides plumbers’ tape, but it wasn’t necessary.

So far, the adapter has been working as designed for the past two years, and still looks pretty good (even if I do say so, myself).