Build base of content – at least 1, ideally 2, new topic(s) per week
My vision document is still a work in progress, but this is definitely a goal that fits within the vision and principles and is SMART.
I still have more things to consider. The biggest elephant in the room is the portfolio that I’ve managed to avoid for, well, for the past 35 years. Likewise, I want to add more CV material, etc. to tell more about me, but I need to keep the Achievable and Realistic elements of the SMART mnemonic in mind, while not ignoring the Timely one.
It might only be one step at a time, but it’s one more step.
As with a product, technical content must work. The challenge is knowing what that actually means and how to measure it. Unfortunately, for a lot of content, this is fuzzy. I’m presenting a paper next month that should help provide a framework for defining this, but, as with Maslow’s triangle, you must do this before you can hope to accomplish the rest.
For technical content, like any product, you must know your audience’s needs to know what works means. At the very least, the content should support the user’s usage scenarios, such as getting started or onboarding, learning common use cases, having reference information to support infrequent, but important, usage or application questions. What this looks like is specific to the documentation and product.
Once you know what works means, then you can tell if it does and determine if it does so consistently. Again, this requires knowledge of the audience–not unlike product design.
This is tough to differentiate from functionality, except that it has the dimension of providing the functionality over time. Measuring this is a matter of tracking the functionality metrics over time.
Once you know what content that works looks like, you can make sure it does so consistently and does so in a way that is as effortless as possible.
Separating usability from functionality is a tough one in the content case. If content is not usable, does it provide functionality? If you look close, you could separate them out. For example, a content set can have all the elements that a user requires but they can be difficult to find or navigate. Likewise, the content might all exist, but be accessible in a way that is inconvenient or disruptive to the user. As with product development, understanding the audience is essential, as is user testing to evaluate this.
Can readers become expert at using the documentation? One could ask if they should become experts, but in the case of a complex product that has a diverse set of features and capabilities, it’s not too hard to imagine having a correspondingly large set of documentation to help users develop expertise.
What does this look like in documentation? At the very least, the terms used the documentation should correspond to the audience’s vocabulary to facilitate searching for new topics.
Not every product supports creativity, nor does every documentation set. However, those that do make the user feel empowered and are delightful to use. A noble, albeit difficult, goal to achieve, but something worthy of consideration.
This might take the form of community engagement in forums, or ongoing updates and tips to increase the value of the documentation and the product to the audience.
I’m still working on the blog’s vision and goals and it occurred to me why authentic was such a sticky wicket–the meaning has been stretched some. To me, it’s summed up as “what you see is what you get,” and therein lies the problem: I don’t look like much, unless you know where to look, I suppose.
The challenge comes when having had to choose between making an impression or making an impact, I’ve preferred to make an impact. Sometimes, on a good day, the impact is what makes an impression. Oftentimes, however, the impact comes at the cost of making an impression, or at least an immediate impression. Sometimes, to be completely honest, I strike out and make neither (or worse). Those, I chalk up to live and learn, and try not to repeat them.
Back to the blog. If I aspire for the blog to have a positive impact and make an impression, but can I do that and be authentic? I think so, as long as the impression comes from the impact. In a world that can’t see past the impressions, however, that’s going to come with a cost. But it’s a cost that’s lower, in the long run, than optimizing for impression over impact.
I think I can get past authentic now that I’ve operationalized it more clearly.
Added a new audience segment: Amateur radio. How could forget that?
Edited the vision to engage in a conversation, not just contribute (i.e. toss things into) one.
Added a new principle: to strive for craftsmanship.
The last one is a personal goal as well and speaks back to how I’ve operationalized authentic. I want this work to have a clean and professional sense about it. If it doesn’t now, I want it to work towards that goal as I go along.
Interesting. By clearing up one principle, I was able to reveal another.
During November and December, 2014, I ran a study to test how varying the design and content of an API reference topic influenced participants’ time to decide if the topic was relevant to a scenario.
I collected data from 698 individual task scenarios were from 201 participants.
The shorter API reference topics were assessed 20% more quickly than the longer ones, but were less credible and were judged to have a less professional appearance than the longer ones.
The API reference topics with more design elements were not assessed any more quickly than those with only a few design elements, but the topics with more design elements were more credible and judged to have a more professional appearance.
Testing API documentation isn’t that difficult (now that I know how to do it, anyway).
The most unexpected result, based on the literature, was how the variations of visual design did not significantly influence the decision time. Another surprise was how long the average decision time was–almost 44 seconds, overall. That’s more than long enough to read the entire topic. Did they scan or read? Unfortunately, I couldn’t tell from my study.
The experiment measured how quickly participants assessed the relevance of an API reference topic to a task-based programming scenario. Each participant was presented with four task scenarios: There were two scenarios for each task: one to which the topic applied and another to which the topic was not relevant and each participant saw two of each. There were four variations of each API reference topic; however, each participant only saw one–they had no way to compare one variation to another.
The four variations of API reference topics resulted from two levels of visual design and two levels of the amount of information presented in the topic.
In the spirit of my last post, I started the vision document for the blog. This wasn’t as hard as I thought, but it wasn’t easy. I ran out of steam at the Principles section. I don’t think that means I’m without principles, just that I want to give them some thought–I want them to be something I can live with, if not aspire to.
That was easy. It took a little bit of thought, but only to decide how to articulate them.
That was pretty straightforward, as well. We’ll see how it holds up as time goes on.
And this is where it got a little sticky.
Be honest and accurate
Be constructive and contribute to improvement
Be honest and accurate – That was easy to put down on paper (virtual or otherwise). Without that as a starting point, the rest is just more Internet flotsam. But I could feel the pressure starting to build.
Be constructive and contribute to improvement – That’s going to take some growing into (so please have some patience). It’s not that being constructive is something I can’t do. Not at all. What’s going to be a challenge is tempering my critical comments (a.k.a. biting my tongue). It’s still too easy for me to slip into my curmudgeon persona. There’s a time and a place to call him to the front of the line, but, it’s usually better if he just stays at home in the rocker on the porch, sipping lemonade, and petting the dog.
Be authentic – …and that’s as far as I got in this try. I got stuck on operationalizing authentic. That shouldn’t be difficult, but for now, I’ll attribute the difficulty to the fact I did all this on a Friday afternoon.
My blog is getting close to celebrating its six month birthday and I’m still finding its voice. Sure, its voice is really my voice, so maybe I’m still finding my voice as well.
From the first post, I started off with some simple, structural rules. Well, rule. Each post should be less than 500 words. That’s about two minutes for the average person to read. It seemed like a good limit to accommodate the reader’s patience and temper the writer’s proclivity to go on and on (and on and on…). Thanks to editor that WordPress provides, I can tell when I’ve hit my limit and several posts have been trimmed down considerably to meet the limit.
There’s more to writing, however, than word count. After limiting the length, the next challenge is the voice and tone. How do I want the blog to sound. Looking back at the topics, they seem to wander around with no apparent direction. In some sense, that’s the nature of a web log, but I’m not sure that’s where I want it to go. This became a more pressing problem as I recently wrote several posts that I’m not sure will ever see the light of day, at least in their current form. They appear to have been written by someone who is very impatient and somewhat upset with things as they are. (Oh, right, that must’ve been me). Whether or not that’s what I meant to say at the time, I’m not sure that’s what I wanted to say. So, I’ll muffle those for the time being. Because it’s easier to edit than create (usually), maybe I’ll come back to them and tidy the up. Constructively, I think they represent my state of mind (unfocused), and my annoyance with that. Fortunately fate has intervened to help turn that around.
After being submerged in the depths of my PhD research project since I can’t remember when, I’m finally able to ponder its nuance and complexity. I find that I’m enjoying the interesting texture that I found in something as mundane as API reference documentation, now that I have a chance to explore and appreciate it (because my dissertation has been turned in!!!!). It’s in that frame of mind that I consider the antithesis of that nuance, the “sloganeering” I’ve seen so often in technical writing.
Is technical writing really so easy and simple that it can be reduced to a slogan or a list of 5 (or even 7) steps? I can appreciate the need to condense a topic into something that fits in a tweet, a blog post, or a 50-minute conference talk. But, is that it?
Let’s start with Content minimalism or, in slogan form, Less is more! While my research project showed that less can be read faster (fortunately, or I’d have a lot more explaining to do), it also showed that less is, well, in a word, less, not more. It turns out that even the father of Content Minimalism, John Carroll, agrees. He says in his 1996 article, “Ten Misconceptions about Minimalism,”
In essence, we will argue that a general view of minimalism cannot be reduced to any of these simplifications, that the effectiveness of the minimalist approach hinges on taking a more comprehensive, articulated, and artful approach to the design of information.
In the context of a well considered task and audience analysis, it’s easy for the writer to know what’s important and focus on it–less can be more useful and easier to grok. He says later in that same article,
Minimalist design in documentation, as in architecture or music, requires identifying the core structures and content.
In the absence of audience and task information, less can simply result in less when the content lacks the core structures and content and misses the readers’ needs. More can also be less, when writers try to cover those aspects by covering everything they can think of (so-called peanut-butter documentation that covers everything to some unsatisfying uniform depth).
For less to be more, it has to be well informed. Its the last part that makes it a little complicated.
Carroll, John, van der Meij, Hans (1996): Ten Misconceptions about Minimalism. IEEE Transactions on Professional Communication, 39(2), 72-86.
It’s hard to believe I’m almost to the finish line…or the starting line, depending on how you look at it.
The defense of my dissertation is just two weeks away. I can’t quite talk about it in the past tense; at the same time, I can’t help but pause for a short reflection before diving into one last sprint to the finish line–preparing the presentation (and myself) for the actual defense.
I didn’t realize this until recently, but it’s amazing the thoughts that have been waiting for a chance to be thought, given the chance. One of the first in line was reflecting on how I got to where I find myself at this moment.
It’s been a long (and occasionally turbulent) chain of events–one that reminds me of Connections, my favorite documentary series of the 80s and 90s. In that series (and book), James Burke, the host, describes a series of unrelated events spread across centuries that come together as something we, now, take for granted–something that would not be possible, if any one of these events had not occurred.
After accounting for some hindsight bias and confirmation bias, that’s basically how I got here–a series of unrelated events, each the result of or the solution to some immediate problem. It would be so much easier to say that this was just another step in my master plan, but, I’ve given up on master plans (not planning, just the notion of running my life according to some master plan). I’ve taken a more Agile approach to life–it’s a model that just seems to fit better.
Humans don’t like to view history in such a random way, so we create, and expect, stories to connect these points in some way that, ideally, makes sense–even if only after the fact. We, as a species, are very story oriented–it’s how we organize the myriad of random, unrelated, and frequently, unintentional events that make up our daily existence.
So, no self-promoting story of how this is yet another example of my brilliance and one more step on my path to greatness. Just a humble acknowledgement that as I finish this step, it’s time to see where to take the next one.
After reflecting a bit, one thing that has been consistent, is that I’ve always been attracted to interesting, if unrelated, problems to explore. Studying for my PhD has provided a steady supply of those, provided a sizable backlog to keep me occupied for some time to come, and left me with quite an appetite for new ones.
But, back to the task at hand. Time to get to work on the presentation for my defense.
I just finished the refresher training for my Flight Instructor (CFI) certificate. This is the eighth time I’ve renewed it since my last check-ride. Yet, for some reason, this time seemed unusually focused on mishaps. Granted, the lessons focused mostly on avoiding them, and surviving them (when they couldn’t be avoided), but mishaps nonetheless.
This year, I had lessons on avoiding and surviving:
mishaps in the mountains
mishaps in helicopters
mishaps in seaplanes
mishaps while teaching student pilots
mishaps in bad weather
Then, as a break in training, I watched the Weather Channel’s “Why Planes Crash.”
Yeah, that was relaxing.
Yet, after all this, I can’t wait to get to the airport and go flying, again. I really enjoy flying so why focus on all this negativity?
So it won’t happen to me. I hope that I never need to apply any of this information, directly. At the same time, I hope to apply what I learned about these mishaps all the time–not just while flying.
Most of the mishap scenarios could be summed up as:
I’ve had a lot of flight training in the 40+ years I’ve spent hanging around airports. The bulk of it–70-80%, I’d guess–involved dealing with emergencies (the rest delt with how to avoid them in the first place). So far, fortunately, these emergency scenarios have only happened to me in training scenarios. While I have a story or two to tell about when things didn’t go exactly as planned, the vast majority of my flights were quite safe.
So, if the probability of an inflight emergency is very low, why spend a disproportionate time in training for them? Because, while they are very low-probability events (0%, ideally), they are very high-cost events.
Is it worth it to spend all that time training for something that is not likely to ever happen? You betcha!! I’m sure the people who fly with me would agree!
What does any of this have to do with technical writing? It’s like I posted in this post on in-flight reading material, some topics provide a little value many times, while other topics provide a great deal of value, but infrequently. The value of content that results, somehow, in a financial transaction is relatively easy to compute: subtract the cost of producing and promoting the content from the gain it provides. Computing the value of content that provides great value but only infrequently, much harder.
Like the flight training that’s kept me from having an accident, how do you measure the value of events (accidents, misunderstandings, errors, etc.) that have been averted or costs that have been avoided?
It turns out I’ve been a social media user (perhaps even somewhat of an expert) for almost 30 years, now. Time to update my resume.
According to this article, amateur radio (a.k.a. ham radio) is the original social media. Um, OK. Let’s compare and contrast…
The article cites these examples:
Talking to people in England and Australia
Using abbreviated words (e.g. BCNU = be seeing you in ham radio and when texting)
Providing communications during emergency situations
Thousands (millions?) of people can hear/read what you send in an instant
OK. There’s no arguing that they have some things in common. In fact, ham radio (Morse code, to be specific) had a speed advantage over texting in a demonstration on the Jay Leno show some 10 years ago. This report from Indiana University had somewhat different results, however, so your mileage may vary–mine would be embarrassing, so I won’t even bring that into the discussion. But, to be fair, let’s look at some of the differences that the report from Indiana University illustrated, if not highlighted.
Ham radio requires a desk-mounted piece of equipment (and a long antenna that wasn’t shown), while texting requires a device that fits in your pocket
Ham radio is somewhat more inconvenient (see previous point)
Not shown, but you can send a text to many more people than you can send a ham-radio message
A text can be sent in English (or any other language that you can type on the keypad), while ham radio messages are coded in Morse code. (Granted, you can also speak over ham radio…like a phone, for example)
While they have some things in common, they are also different in many ways.
I have fun with ham radio and I’ve talked to far-away places. For the past two years, I’ve used it to support humanitarian work in eastern Honduras. That I can string up a wire and talk to someone in Brazil without any additional equipment beyond the radio that’s connected to the wire, never ceases to amaze me, but is it social media?
I’ll settle for calling it technical communications.