The symbiotic relationship between documentation and application development

One of my current projects involves documenting processes for an application that are still under development. As such, much of what I write may change, depending on how processes are changed during the course of development.

At one point, I tested one of the processes so I could determine functionality and document it. In doing so, the process came back with an error message that I wasn’t expecting and didn’t have any user-friendly information, other than a cryptic error code. I contacted one of the developers working on the application and told him what I found. I gave him the error codes I experienced and steps I took to get them. He told me, “you’re coming across bugs that we didn’t even know we had.”

It occurred to me that I was doing more than just documenting the application. I was also acting as a beta tester.

One aspect about writing technical documentation is learning about what you’re writing. In order to write about a process, you need to understand how it works. If you’re documenting an application, the best thing you can do is run the application in a safe environment (such as development or a sandbox), learn how it works, and use it to document steps and capture screens. In doing so, you come across application bugs and even come up with ideas to make the application even better.

I’ve long argued as to the criticality of documentation. It records important information and serves as a reference. However, until this point, it didn’t occur to me that the document development process could have a symbiotic relationship with application development. To me, this adds further fuel to the argument that documentation is critical and required.

Advertisements

Testing is important for documentation, too

For those of you who produce documentation, how often have you sent your documents out into the real world, only to have it returned to say it’s all wrong? Or have you ever received feedback saying things like “this is difficult to read,” “I can’t follow this,” and so on?

One of my most frustrating aspects of technical writing is any time — every time — that I ask people to review what I write, my request goes ignored. As I’ve written before about the nature of documentation, requests for document review are often met with indifference and disrespect. A lot of people just don’t think it’s important. It is critically important. I don’t always know about the subject that I’m writing, and I’m often at the mercy of subject matter experts (SMEs) who know more about the subject than I do.

It’s not just the subject matter, either. I’m the first to admit that I’m a grammar snob, but I’m also not perfect, either (I was not an English major, after all). Many a time have I confused “who” and “whom,” ended a sentence with a preposition, used an apostrophe-S for a possessive, forgotten to put “I before E,” and so on. Likewise, I try my best to design documentation for better readability, but I also realize that there’s always room for improvement, and it often takes another set of eyes to provide a way to make something better than never occurred to me.

I’ve argued before that documentation needs to be treated like software. Like software, documentation has a life cycle. It needs to be maintained. And as such, it needs to be tested. Documentation, like software, will have bugs that need to be addressed.

It also isn’t just a matter of reading a document and saying “yeah, this looks good.” User testing should also be a part of it. If you’re writing step-by-step instructions, how will you know if they’re accurate? Back when I was a grad student at RPI, one of my writing projects included user testing as part of the project. I wrote a set of instructions for a procedure in my office (the document served a dual purpose for me — not only was I getting graded for it, I was also contributing to my workplace). To test it, I asked one of my co-workers to follow it as she went through the procedure I’d documented. She caught issues with my steps that I never would have caught on my own. From that user testing, I corrected the issues and made the document even better.

As a technical writer, I expect — and demand — people to review, test, and scrutinize what I produce. I demand excellence from myself. In order to achieve excellence, I need other people to review what I do. And I want to know that what I’m producing is of good quality and factually accurate. Without that critical feedback, I’ll likely not know whether or not I’m doing my job.

Collaboration, cooperation, and competition

This is another article based on stuff that I picked up from SQL Saturday #814.  This time, I’ll talk about Matt Cushing’s presentation about networking.

Whenever I’m speaking at a SQL Saturday, I always make it a point to attend sessions that are similar to mine.  At #814, I met Matt Cushing, who was doing a session on networking.  In fact, our presentations had very similar titles; they both started with “Networking 101.”  That very much caught my attention, and once I finished my own (my presentation was in the time slot immediately before his), I went to his room to catch his presentation.

A big reason why I attend presentations similar to mine is that everyone is different, and will therefore present differently.  Other people will have different perspectives of the same topic.  I want to see these other perspectives.  They might have ideas that will help me enhance my own presentations.  Every time I attend a session in which the topic is relevant to my own, I come across something that either never occurred to me, presents an idea in a different way, or reinforces concepts in my own presentations.  These are important, and they help me make my presentations even better.

Matt gave a great presentation!  I found his own self-assessment on his ‘blog.  I found out that it was Matt’s first-ever SQL Saturday presentation.  I had no idea!  He did a great job with it.  (Matt, if you’re reading this, well done!)  I don’t remember all the points from his session (I’ll need to download his presentation slides), but one takeaway was that “competition is good, cooperation is better.”  (This thought inspired the name of this article you’re reading now.)

This concept of cooperation is applicable to countless situations, and SQL Saturday presentations are no exception.  Many presenters refer to other speakers or other presentations; even in my own presentations, I’ll encourage audience members to go check out other presentations that are similar to my own topic.  (Ed. note: I need to make sure I add a reference to Matt’s presentation in my own slides!)  Matt and I joked that we should encourage SQL Saturday organizers to schedule our sessions back-to-back; we even went as far as to say that we should do a joint presentation.  (Matt, I’m game if you are!)

In a way, Matt is a competitor in that we did similar presentations.  However, we were both able to learn and feed off each other, which enables us both to improve; it’s a win-win for both of us.  Competition is a healthy thing; it drives us to do our best.  But when you cooperate with your competition, there’s no telling what you can accomplish.

SQL Saturday #814 — the debrief

I had a great time speaking at SQL Saturday in Washington, DC this past weekend!  Chris Bell and his team put on a great event, and it’s one to which I will definitely submit again!

I wanted to write this up quickly for a couple of reasons.  One is to acknowledge the SQL Saturday #814 team for the great job they did!  I also wanted to write this to note a few things that I experienced — enough so that I wanted to ‘blog about them; you will see articles about these this week while they’re fresh in my mind, and I wanted to note them while I was thinking about them.  First, Eugene Meidinger asked me what I thought was a very good and legitimate question.  Second, I walked in on the tail end of a presentation by Kevin Feasel that I definitely wish I had seen.  Third, I sat in on another presentation by Matt Cushing that I thought was very good!  Finally, I sat in on a post-event session by George Walters about job opportunities at Microsoft, which I also found interesting!

I will be addressing these thoughts in upcoming ‘blog articles, so stay tuned!

If at first you don’t succeed…

“Gotta run a little faster, gotta reach for the sky, gotta come a little closer, even if I lose, I gotta try…”

— Kansas, “Inside Of Me”

I will confess that the song lyric above is one of my favorites, and probably one of my most overused quoted lyrics.  It isn’t the first time I’ve quoted it to start a ‘blog article, and it likely won’t be the last.  I’ll admit a level of bias because it comes from my favorite band, but the lyric also talks to me in a way that few do.  I came across a couple of things today that reminded me (again) of this lyric.

First, I received an email that I had been turned down for a speaker’s program, sponsored by my fraternity, to which I had applied.  Not a piece of news that I wanted to hear, but I took it in stride.  I saw something that interested me, I thought I’d be a good fit, and I gave it a shot.

(I should note that, as part of the application process, I recorded a presentation video of myself doing a “lightning talk” that I entitled “Why you need to be on LinkedIn.”  I wanted to wait until I’d heard about my application decision before making this video more publically available.  I’m posting the link here for all of you to enjoy — or trash, whatever the case may be!  I realize that the audio quality is not that great; I apologize in advance for that.)

(I should also note that I replied to the email, thanking them for considering me, and to ask for feedback as to what I could’ve done better.  As I’ve written before, feedback is always important if you want to get better.)

Second, I came across this article that talks about tomorrow night’s basketball game: Syracuse vs. Cornell, or as I refer to it, the “Boeheim Family Reunion.”  (For the benefit of those of you who are clueless about college basketball, Jim Boeheim is the Syracuse men’s basketball head coach, his younger son, Jack “Buddy” Boeheim, is a freshman on the Syracuse team, and his older son, Jimmy, is a sophomore playing for Cornell.)

What I wanted to note about the article was a quote from the family patriarch.  Some background info: the Boeheim men are notoriously competitive, a central point of the article.  The article mentions: “Jimmy talks about the endless games of Candyland they played against their dad, the loser always demanding a rematch. Jim Boeheim never let the boys win. Victories needed to be earned or what was the point of competing?”

It got me thinking that these were a metaphor for one’s career and life in general.  Your career and your quality of life are often competitive, sometimes even cutthroat.  You have a choice: either forget about the entire thing, or give it another shot.  In regards to the former, I ask a question: how important is it to you?  If it isn’t important, not worth your while, or it isn’t a big deal, then give it up and move on to whatever is next.  But if it is important, then it’s up to you to get off the mat and keep fighting.

It’s one of the ideals that keeps CrossFitters going.  It’s about getting better.  Granted, I’ll likely never get to the level where I’ll be competing against Mat Fraser, but as long as it’s possible for me to improve (which is the case in just about anything and everything I do), I’m going to keep going.

In regard to the speaker’s program, being accepted would’ve been a nice boost to my speaking endeavor and potentially my career.  But if I wasn’t accepted?  No biggie.  Hey, I came, I saw, and I gave it a shot.  C’est la vie.  All I can do is learn from it and take another crack at it when (or if) another such opportunity comes around again.  I can sleep at night knowing that, at the very least, I tried.

I’ll stop short of quoting the infinite number of clichés, memes, or articles (to which I’m adding yet another by writing this) about picking yourself up and trying again.  All I’ll say is that they’re true.  Just keep going.  If at first you don’t succeed…

How do different cultures use your documentation?

The other day, I sat in a meeting in which we were talking about our product documentation, and someone mentioned something that had never occurred to me.

It had to do with who used our product documentation.

I found out that native English speakers (for the sake of this article, I’ll refer to them as “arch-typical American end-users” — whatever that means) mostly ignored the documentation (that I had written), inferred what they needed primarily from the application interface, and used the documentation primarily as a reference source.  This was something I’d anticipated, so naturally, I developed the document with that mindset.

However, I learned that users whose first language was not English utilized the document much, much differently.  (Disclosure: I currently work in an office where the majority of my coworkers are Asian-Indian.)  Many of them first read the documentation thoroughly before using the application.

I don’t know how much these people used the document as a reference guide as compared to how much they used the UI — we didn’t go into that discussion — but it completely changed my mindset as to how to approach documentation development.  I haven’t (yet) done any research, but I am now curious as to how people from different cultures and backgrounds approach documentation.  I have no doubt that this topic has been researched; if anyone knows of any authors or references, feel free to say so in the comments section.

For those of you who don’t know me, I should mention that I am Asian-American (specifically, Korean-American), but I am a native English speaker.  I don’t speak any other language fluently.  I do not speak Korean (what little I know came from what little my grandmother tried to teach me and from M*A*S*H reruns), and my personal foreign language experience comes from my German classes in high school and college.  That puts me in a unique situation; when it comes to my writing, my initial audience is American-English speakers, but my ancestral background makes me appreciate audiences from other cultures as well.

Cultural differences in communication are always an interesting topic.  I remember reading an article about how Chevrolet had issues with selling a particular model of their car in Spanish-speaking countries, because “Nova” translates to “not going.”  I also recall a conversation with someone who mentioned that a simple American gestures as a thumbs-up is the equivalent of “flipping someone the bird” in some other countries.  So it goes to show that what you’re trying to communicate could actually be miscommunicated, depending on your audience’s culture.

I’ve espoused time and again that a writer needs to know his or her audience when developing a document, and I continue to do so.  This realization made me realize that my audience is more diverse than I thought it was, and that I will need to plan for that whenever I am developing documentation.  And it’s not just a matter of what I’m writing in my words — it’s also a matter of how my document will be used.

So I guess the moral of the story is to be wary of what you’re writing.  You never know who will be reading — or how they will be using it.

A few words can make a difference

A couple of weeks ago, the Rensselaer Polytechnic (the RPI student newspaper) published a couple of op-eds in regard to the situation at RPI.  (My friend, Greg Moore, wrote a piece a while back related to this issue.)  In response to the op-eds, I decided to respond with my own letter to the editor.

This morning, a friend posted to my Facebook that my letter, to my surprise, was garnering some attention.  I won’t say that it’s gone viral, but apparently, it’s caught a number of eyes.

I should note that my donations haven’t been much.  I was only a graduate student at Rensselaer, not an undergrad, so the social impact on my life wasn’t quite the same, and other financial obligations have kept me from donating more of my money.  That said, I’ve donated in other ways; I’ve been a hockey season ticket holder for many years (going back to my days as a student), I’ve attended various events (sports, cultural, etc.) on campus, and I’ve donated some of my time to the Institute.

Although my donations have been relatively meager, more importantly, I wanted to spread the word that I was no longer supporting RPI, and exactly why I was discontinuing my support.  How much I was contributing isn’t the issue; the issue is that I am stopping contributing.  For the first time in years, I have no intention of setting foot in the Field House for a hockey game during a season.  I wanted to make clear exactly why.  A large number of alumni have announced that they were withholding donations.  I wanted to add to that chorus.  It wasn’t so much how much I was donating; rather, I wanted to add my voice, and hopefully encourage other students and alumni to take action against an administration that I deem to be oppressive.

One of RPI’s marketing catchphrases is, “why not change the world?”  It looks like I’m doing exactly that with my letter.  Don’t underestimate the power of words.  Indeed, with just a few words, you can change the world.