Can Agile and documentation projects co-exist?

When I spoke at the New England SQL user group meeting yesterday, an interesting question came up. An audience member spoke about Agile development, and he mentioned that, because of the nature of Agile, document projects were doomed to fail.

At this point, I should mention a few things.

  1. I currently work in an environment that uses Agile development methodology.
  2. Just because I work in said environment doesn’t mean I know anything about Agile.
  3. Even as my workgroup’s technical writer, I am considered a highly valued member of the workgroup.
  4. Somehow, we make it work.

In regards to #4 above, the gentleman had a simple question: “How?”

This question came up during a point in my presentation in which I argued that document projects should be treated like software — in that, in an ideal environment (stop snickering!), a formal document should be subject to planning, development, and testing. This is a point that I’ve alluded to before.

The person asking the question went as far as to say, “if you can make the case as to how Agile can make technical writing projects work, then you should make a presentation out of it — and I’ll even help you sell it to Agile.” He even gave me his business card. Indeed, one of my big reasons for writing this article is as a reminder to myself to revisit this subject — after I’ve had a chance to do some homework about Agile development. It’s something I’ve been meaning to do; I even went as far as to begin a draft article about Agile development.

So, to the gentleman who brought up this (great) question, you were heard. And I will make sure that I come back to this at some point — once I’ve had a chance to do my homework on Agile.

It was the best of times, it was the worst of times

Steve Jones recently asked: what were your best days at work, and what was your worst?  He also issued a challenge to write about our typical days at work.  In terms of writing about a typical workday, I have the first of four (per Steve’s challenge instructions) draft articles warming up in the bullpen; hopefully, I’ll crank that one out sometime within the next week or so.  But in the meantime, for this article, I want to take a moment to address the best and worst days.

In terms of the worst day, I don’t think there is any contest.  I think it’s pretty safe to say that 9/11 was my worst day at work.  (For the benefit of those of you who don’t feel like clicking my article link, I worked for a company that had an office in the World Trade Center — when 9/11 happened.)

In terms of the best days, however, that requires a little more thought.  It’s not that I haven’t had any great days — that isn’t true — it’s just that there are a number of them, and having been a working professional for (cough! cough!!!) years, trying to pick out a few that stand out over the years is difficult for me to do.  So what I’ll do is pick out a few project victories that I’ve had over the course of my career.  Granted, I’m picking these from the top of my head, and there very well might be others that were more significant that I’m not remembering right now, but for purposes of this exercise, I’ll write about some projects with which I was involved and take a measure of pride.

I’ll start with a project related to the worst day that I mentioned above.  One of my tasks was to maintain an inventory of the servers in our data centers.  For a long time, this was a tediously manual task.  I went through our data centers with a clipboard, checking to see what servers were in each rack, noting any changes and adding new servers and racks that I found.  I drew a map of each room in Visio, even going as far as to count the floor tiles so that I could draw them to scale.  I populated the maps with boxes representing server racks and came up with a naming scheme directly tied into a row-and-column location scheme, making it possible to identify and label each rack so they’d be easy to find.  Included with the maps was a listing of servers within each rack.  I maintained the Visio file on my PC, making sure it was backed up to a departmental file server, and keeping hardcopies in each server room as a reference for various IT workers.

Because this was a manual process, the maps were never completely accurate — I have no doubt that new servers were continually added in-between map updates — and it was a tedious process.  All the while, I kept thinking, “there has to be a better way to do this.”  Sure enough, I found one!

I discovered that all our servers included a product called Insight Manager.  Among other things, it included the ability to collect server BIOS information and store it in a format suitable for importing into a database such as SQL Server.  Using the Insight Manager data structure as a template, I set up a SQL Server database on one of our departmental servers and created a system that enabled it to import data from any server on demand through Insight Manager.  I now had a central database with server data that could be updated at any given time!

Of course, data isn’t information unless it can be interpreted and understood, so the next step was to create an interface for it.  I was responsible for maintaining a departmental intranet site; although it was an internal intranet, I treated it as though it was a full-blown web site.  I created a web site to display the server data stored in my back-end.  I took my Visio server room maps and created image files from them.  From the image files, I created image maps that enabled a user to click a server rack on the map, drilling down to a list of servers in that rack.  Clicking on a server displayed data for that server — serial numbers, IP addresses, applications, and so on.

My server inventory system, which I previously had to update manually, was now automated!

This project was a major milestone for my career.  It was my first significant foray into SQL Server.  (At that time, I hadn’t yet learned about data normalization; had I known about it, I could’ve made the back-end even better.)  It gave me some experience with image maps, HTML, and classic ASP (the technology used on that intranet server at that time).  Most of all, it was my first taste of what it was like to be a web applications developer.

Memories of this project also reminded me of another good day I had on the job.  One particular day, I traveled to remote offices in Yorktown Heights and Middletown to survey their data centers for the server inventory system that I just described.  I hopped into my truck (I owned a small Toyota pickup truck at the time) and drove to Yorktown.  It was a gorgeous picture-perfect day; the sun was out and it was comfortably warm with low humidity.  It was comfortable enough that I left the air conditioner turned off and drove the entire trip with my windows rolled all the way down.  It was the kind of day where I wished I owned a convertible!  My route between the Yorktown and Middletown offices took me through the Bear Mountain area, including traversing the Hudson River over the Bear Mountain Bridge.  If you’ve never driven through that area of New York State, it is an absolutely picturesque and beautiful drive.  The entire trip was so fun and relaxing that it did not feel like a business trip at all; I actually felt as though I was on a vacation!

Finally, I want to talk about one last project in which I had a hand.  In one of my first jobs out of college (my second job out of school, actually), I was responsible for supporting my company’s document imaging system at a client site (a client that eventually ended up hiring me directly).  One of the system’s components was a WORM optical platter jukebox that was in constant use and occasionally needed operations maintenance, which ranged from simple tasks such as inserting an optical platter to complex ones such as restarting it when it locked up.  The device had to be operational 24/7, even at hours when we were not in the office.

I was tasked with putting together a small set of instructions — nothing big, just a few pages — that explained how to perform these tasks, including the correct way to insert a platter, what to do when (unfortunately, not if) the machine stopped working, and so on.  It needed to be written in such a way that the night maintenance staff could maintain the device.  So I sat down in front of my PC with a blank MS Word file and said to myself, “if I was a member of the night staff, what would I want to read that would enable me to perform these tasks?”

I had intended for the document to be a simple three to four page quick reference.  As I wrote and came up with more ideas that would help the readers who would be using it (including the innovative — for me — use of illustrations), the document kept getting bigger and bigger.  I don’t remember how big it eventually became, but I think it was somewhere in the ballpark of thirty pages.  I had absolutely zero technical writing experience at the time; I wrote the document completely by instinct.  I didn’t really know what I was doing; I just did things (illustrations, headers, subject organizations, etc.) that made sense to me.

The final product was a huge success — so much so, in fact, that management developed a training program based around this document.

A couple of years later, I discovered that nearby Rensselaer Polytechnic Institute had a Masters degree program in technical communication (note: I am not entirely sure if the program still exists).  I had been interested in pursuing a graduate degree, and I thought the program sounded interesting, so I decided to apply.  During my application interview with the faculty, I brought along a copy of that operational jukebox document I’d written.  I explained that I’d written the document completely by instinct and with no knowledge or experience in technical writing whatsoever.  The faculty seemed to be impressed with my effort on that project.

I was accepted into the program.  I now have an MS from RPI hanging on my home office wall and listed on my resume.

This article ended up being a lot longer than I expected.  Looking back on this exercise that Steve assigned, I suppose my good days at work were more significant than I thought.  These projects were major events that ended up shaping this professional career.  I suppose the moral of the story is not to underestimate job achievements.  You never know where they might lead!

The document development life cycle

A recent work request reminded me of production life cycles.  I got an email regarding a user guide for an application that I had written earlier this year.  She said she was looking for something similar.  She asked me how long it would take.  I told her that I would need to look at the application, but I also said there were a number of things to consider, including how much access I could have to the application so I could test and document it, who would be available to answer any questions I had, who would be able to test and review the document, the document format, and so on.  (On hindsight, I also realized that I’d forgotten to ask a very important question: who is the audience?)

The conversation reminded me about the importance of the document development life cycle.  In an earlier article, I talked about a number of issues that frustrate people who understand technical communication and documentation.  This is another frustration that is poorly understood and widely ignored.

I’ve had the privilege of having worked in both software development and professional document development environments.  Many people fail to understand that there is no difference in the production process between the two environments.  To put it another way, the development life cycle between the two is no different!!!  The software development life cycle (SDLC) is widely known and an industry-standard term.  But if you’re not a technical writer or communicator, when was the last time you heard any mention of a document development life cycle?  For that matter, are you even aware that such a thing exists?

It seems to me that most people aren’t.  How many of you have been frustrated when you’re given a documentation project, whether it’s an application, a process, or a product, and been told that it needs to be finished in a couple of days (or even a couple of hours)?  This is completely disrespectful to technical writers, and it upsets me to no end.

An example of a software development life cycle
(source: SoftwareTestingMaterial.com)

Like software, producing good documentation follows a life cycle.  Here’s a sampling of what takes place when developing a document.  Document requirements must be defined: what is being documented, what is the scope, and so on.  And let’s also not forget what may very well be the most important requirement: who is the target audience?  The document must be designed and written.  This involves organization, layout, and design.  Writing it is no small task; I’ve written before about how hard it is to interpret ideas that come from a subject matter expert (SME).  Once a document draft is written, it needs to be reviewed (“tested”) by an SME for accuracy; are the ideas conveyed in the document correct?  Adjustments to the document will likely need to be made, and it will need to go back to the technical writer for editing and updates.  Document format needs to be considered; will it be deployed as a PDF document, or will it be stored and maintained in an online format, such as a Wiki, Sharepoint, or Confluence?  Speaking of maintenance, bear in mind that if the application or process is changed, the document will likely need to be changed as well.

Documentation is a critical, yet overlooked and disrespected, profession in technology.  A technical writer cannot be expected to produce a quality document in mere hours.  As with all quality products, documentation also follows a life cycle.  Whenever the document life cycle is properly followed, the result is a quality document, which, in turn, results in satisfied customers and a positive reputation for your organization.

Always ask someone to test your product

This morning, one of my colleagues posted this message to our Slack channel:

please ask someone else to test your code before pushing it

It brought to mind an important thought (and more ‘blog article fodder): any time you produce something, regardless of what it is — a software application, documentation, a presentation, a music composition, a dish you cooked, etc. — always ask someone else to test it out before you send it out for public consumption.

That testing could take several different forms — it could be an end user trying your application, somebody reading your document, listening to your presentation or your music, trying your dish, and so on.  Testing results in feedback, which results in improvements to your product.

Whenever we produce something, we have our own vision — and our own biases — as to how the product should come out.  We expect our products to be perfect as resulting from our own visions, and we expect (and demand) that the consumers adhere to our visions and how we expect the products to be viewed or interpreted.

Unfortunately, we are blinded by our biases.  The world does not share our same visions.  People who use our products will never, ever, perfectly interpret how our products should be consumed.  More often than not, we’ll find that what we produce will be used or interpreted in ways that never occurred to us.

Even in my own workplace, I write and edit a lot of online documentation.  Much of what I write comes from other sources, often about topics about which I know little (or, sometimes, nothing).  I try to write material based on the information I have at hand.  Very often, I come across gaps that need to be filled.  I’ll do my best to ask original authors what was intended, or to dig for information to fill those gaps.  But in absence of those resources, I end up making assumptions and using my own intuition to fill in the blanks.  Those assumptions might not necessarily be correct, and what I write could end up being different from what was originally intended.  It is for this reason why I am constantly asking my colleagues, “take a look at what I wrote.  I want to make sure what I wrote is accurate.”

In a manner of speaking, creating products is a form of communication — in that what we produce results from an idea in our heads, and the end users — the consumers — are the ones “listening” to the communication — in this case, the end product.  If you are familiar with the basic communication model, a sender creates a message, a receiver interprets the message, and the receiver reacts to the message in the form of feedback.  Producing a products works in exactly the same way — a producer creates a product, a consumer uses the product, and the consumer reacts to the product, generating feedback.  In between the sender and the receiver is “noise” that degrades the message or the product (it is not literally noise — the “noise” can simply be the fact that the sender’s and receiver’s interpretation of the message are not one and the same).

So, any time you create some kind of product, always ask someone else to try it out.  You’ll find that the person’s feedback will result in tweaks to your product.  And you will end up with a better product.

My first podcast interview!

About a week ago, I received an email from Carlos Chacon of SQL Data Partners inviting me to take part in a podcast.  This was my first such request, and I jumped on the opportunity.

The podcast recording took place last night.  My topic was along the lines of “writing and communication: why it matters to data professionals.”  It was a lot of fun, and I very much enjoyed talking to Carlos and his partner, Steve.

The podcast should air sometime in March.  It will be posted on their ‘blog.  When it does, I’ll make sure that I post a link to it!

Writing blind

“Life is like a sewer.  What you get out of it depends on what you put into it.”
— unknown

As a technical writer, one thing I often request is access to the product — whether it’s a web site, application, device, tool, etc. — that I’m writing about.  In order for me to write something about a product, I need to know what the product is, how it works, and how to use it.

Unlike, say, a novelist or a creative writer, technical writing topics usually do not originate from the writer, but from something or someone else, such as a process, procedure, or product.  In order for the writer to produce a good, quality document, he or she must know about it — what it is, why it’s significant, what it looks like, how to use it, potential issues, and so on.

What happens, however, when the only resource you have is someone else’s description?  Moreso, what happens when that person is (by his or her own admission) not a writer?  (There’s a reason why this person gave you this project in the first place.)  I recently worked on a small side project that reminded me just how important this is.  Granted, it was only a small and minor project, but it did remind me about just how critical it is for a writer to understand the subject.

Imagine the following situation: you need to add more windshield washer fluid to your car.  You open the hood and see different caps.  You know there are caps for washer fluid, engine coolant, oil, and so on.  However, they are not clearly marked (as far as you can see), and you don’t know which one is which.  Opening the wrong cap and filling it with the wrong fluid will damage your car.  You call a friend who tells you to look for a plastic reservoir filled with blue liquid.  Trouble is, there are two of them (one is washer fluid, the other is coolant).  Your friend tells you to look for something that looks like a windshield on the cap.  Okay, you see something that looks like it might be a window with a wiper going across it.  That’s it.

Sound frustrating?  These are the kinds of situations that technical writers and communicators deal with regularly and on a much larger scale.  In order to write a technical document, the writer must have a source of good data — whether it’s hands-on experience, pictures, data graphs, good descriptions, etc. — in order to write a quality document.  A bad or inaccurate source of data will often result in a bad document.

Developers, coders, and data professionals have a name for this kind of situation: garbage in, garbage out.  In order for data to be processed into information (I won’t get into it now, but there is a difference between data and information — that’s another topic for another time), you need to have good data to start.  Bad data results in bad and inaccurate information.

Writers cannot read minds.  Unless a subject matter expert (SME) can properly convey his or her idea (and it almost never happens on the first go-around), it might take several iterations and lots of SME-writer interaction before the draft is correct.

Professional chefs have a term for ensuring everything is set up and in place before cooking: mise en place (pronounced “MEES-in-plahs”).  While the technology sector does not use the same terminology, the principle still applies: make sure things are in place and ideas are properly conveyed before information processing (including documentation) can occur.  Otherwise, trash at the beginning of the process will likely result in trash at the end.

SQL Saturday #694, Providence

This morning, I saw a ‘blog post from my friend, Greg Moore, who wrote about his upcoming presentations at SQL Saturday in Washington, DC this Saturday.  Greg is an excellent presenter, and I always recommend his presentations anytime.

It also made me realize a few things.  First, my own SQL Saturday presentations are coming up quickly — this Saturday (December 9), in fact.  Warning: dates in calendar are closer than they appear!  So I figured I should do more to promote my own presentations.  Come hear me speak at SQL Saturday #694 in Providence, RI.  I will be giving the following two presentations:

Providence SQL Saturday is a special one for me.  I first spoke at Providence two years ago, and it represented a couple of milestones.  First, it was the first SQL Saturday I ever attended that was outside New York State.  The first ones I attended were all in New York City (and to this day, I still try to attend that one whenever I can, regardless of whether or not I’m speaking) or in Albany.  Second, it was only the second time that I had ever presented at a SQL Saturday.  The first was earlier that summer, when I spoke at my hometown SQL Saturday in Albany, NY.  In fact, the presentation I gave — talking to non-techies — is the same one that I will be giving this Saturday.  I’ve since added to it and polished it a bit.  Hopefully, this presentation will go even better than the last time I gave it in Providence two years ago!

If you’ve never been to a SQL Saturday, check it out.  It’s a great day of learning (and it’s free — although there’s usually a nominal fee for lunch), it’s a great opportunity to network with industry colleagues, and it’s a fun social event (seriously, it is)!  I look forward to every SQL Saturday that I attend, and this Saturday should be no different.

Hope to see you there!

Upcoming SQL Saturday dates for me

Looks like my SQL Saturday schedule will be busy!  Here are my upcoming dates (and I admit that I’m writing this for my own reference as much as anything else).

Scheduled to speak

I am scheduled to speak at the following event:

Presentation abstracts submitted

I submitted my presentations to these events; no guarantee that I will be picked to speak at any of these, but you never know:

Save the date

Event that is on the calendar, but not yet scheduled (hence, there’s no link to it yet); I intend to submit to it when it goes live:

  • July 28, 2018: Albany, NY (my hometown SQL Saturday!)

SQL Saturday is a great, free conference for anyone who wants to learn more about SQL Server.  Many interesting topics are presented, it’s a great opportunity to network, and it’s a lot of fun!

Hope to see people there!