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

Jobs That Beat The Caring Out Of You

“The beatings will continue until morale improves.”

Unknown

Before I get into this article, let me say that this appears to be a thread going around today (on April Fool’s Day, no less). I decided to add to the chorus.

But before I do, here are the other articles (all with the same title) that inspired me to write this. I especially list Jen first, since she appears to be the one who started this thread.

Feel free to read their stories. Go ahead. I’ll wait.

Okay, now I’ll add on with my own story. This involves the company where I worked before I latched on with my current one. For reasons that I think are obvious, I will not name the company (I’ll simply refer to it as “The Company” — and I think capitalizing even that is giving it too much credit), nor will I describe who they are or what they do, other than that they’re a software company. I will leave it at that. Those of you who know me well will likely know the organization to which I refer. Everyone else… well, you’ll just have to play along.

So here’s the scoop. Essentially, I was fired from The Company.

I suppose a little background story is in order.

I’ll start at the beginning. I was hired at The Company as an application developer. I was hired because I have experience with classic ASP — an old technology that isn’t widely used anymore. It seemed like a good place, and I was looking forward to getting started with The Company. Indeed, the people were friendly, and I am still friends with many of them to this day.

Nevertheless, there were warning signs from Day One, and I didn’t pay heed. Only now through hindsight do I recognize those signs.

The first sign: my very first day on the job, I was poking around the application. My very first question: “where is the documentation for this?”

And people looked at me as though I had two heads.

There was absolutely no code documentation anywhere. It simply did not exist. It barely even existed as code comments, and even those were rare. I was expected to understand how the code worked just by looking at it and remembering how it all worked as I went through it — without writing anything down. I’ll say it again for emphasis: I was expected to be able to do this.

That should have been a major red flag there. But there’s more.

There appeared to be a lot of employee turnover at The Company. People seemed to come and go on a regular basis. As I would tell people years later, “this place didn’t just have high turnover, they had a revolving door.” This was another major red flag.

It seemed like a fun place to work. Once a year, they closed the office for a day for a company picnic. It included a golf outing, food and games. Every year around the holidays, they would have a holiday party where they would give out large prizes (including cash bonuses and TVs), and The Company even sprung for a hotel for the night. They would do it again in late winter or early spring, and refer to it as a “blow off steam” party. They regularly had a massage therapist come to the office once in a while to give free massages. I even remember one day where The Company achieved a major success (it was either a successful release or gained a major client — I don’t remember which), and to celebrate, they had girls walking up and down the aisles with trays of hors d’oeuvres. I didn’t even need to eat lunch that day. Indeed, it seemed like a party atmosphere, and they made it out to be a fun workplace.

(I’m guessing that, at this point, those of you who know me know who “The Company” is.)

However, looks can be deceiving. And a “fun party” workplace doesn’t do much for one’s career.

To say that I struggled as a developer is an understatement. I couldn’t grasp a lot of what The Company was doing in their applications. I did my best to keep up, but the lack of documentation was a major stumbling block. I started to doubt my own coding skills — and a lot of that doubt still continues to this day. It’s one of the major reasons why I’ve been moving away from my technical skill sets. I do enjoy writing code, but that experience made me question whether or not I was really cut out to be a developer. At one point in my career, I was hoping to do more as a developer, but my harrowing experience with The Company has since dashed those aspirations.

Let me go back to the part about lack of documentation. I made it clear to management that I had a Master’s degree in technical communication and professional experience as a technical writer. I let them know that I was willing to take on documentation duties, and offered my services as such. They had a company Wiki that was underused, and only a few people had access to it. I asked for, and got, access, and documented what I could, which wasn’t much.

There were clients asking for a system administration guide. I saw what they were sending out. My opinion of the document — the only good place where it could’ve been used was the bathroom. The document was absolutely horrific. It had absolutely no structure whatsoever, and it was impossible to read. It basically looked like a bunch of scratch notes just thrown together into a Word doc that was given to clients — which was pretty much what it was. The excuse I got was, “these people are techies just like us. They don’t need formal or good documentation.”

I offered to rewrite the system admin guide, and I did what I could. I threw out the old guide and rewrote the entire thing. It wasn’t perfect, but it was an infinite improvement over what they had before.

The Company insisted on an addendum to the system admin guide. They insisted on sending out a document — which they insisted on writing in Excel (!!!!!!!!) — out to clients. They sent it out without review, and likewise, it was horribly written.

The Company wasn’t just disinterested in documentation. They were openly hostile to it.

The Company had absolutely no interest in developing their employees. The prevailing attitude was, you don’t need to develop your skills. You’re going to do what we need, you’re going to do it our way, and you’re going to do it well.

Now, I’ve practically made an entire career out of adjusting to my environment. When I realized that I wasn’t going to make the grade there as a developer, I offered my skill sets in other areas, especially in communication. I offered to write full-time. Eventually, they moved me to an area where I was responsible for client software releases. They were showing me that they had no interest in me and my development. They didn’t care about what I wanted. They just wanted something from me — something I could’ve offered, had I been in a decent, nurturing working environment — which this was definitely not.

I was called to HR and told that I was on probation. I had (I think it was) sixty days to shape up. So I worked harder. I worked on improving the quality of my work. I picked up the pace.

I should note that two things happened around this time.

First, I updated and actively (and discreetly) pushed my resume. I had gotten to the point that I was absolutely miserable working there, and wanted to leave as soon as I could. I wanted it to be on my terms, not The Company’s.

Second, I wrote this article. I could see the handwriting on the wall.

Several weeks later, I was called into HR again. I was told I was being let go. They noted the effort I was putting in, but said I was not improving my skill sets they way they wanted.

Not once during my probation period was I told that that was what they wanted me to improve. Not once.

I was cordial during my interview with HR. I asked questions like, “well, how will such-and-such be handled after I leave?” That was the face I gave them. In the back of my head, I was silently saying things to them that I cannot repeat in this article.

There is actually some more details to my story, but I don’t want to discuss them. By now, I think you have the gist.

I told myself then and there that I would never recommend The Company to anyone ever. I didn’t burn bridges with them; they burned them with me. The Company effectively discouraged me from pursuing positions as a developer. I could’ve been a lot more in my career than I am now, and The Company took that away from me.

I have since spoken with other people who experienced The Company, and every one, to a person, has said similar things. One of them went as far as to say, “I hope The Company goes out of business.”

So I suppose the moral of the story is to beware of bad places to work. If you’re not careful, they could adversely affect your career.

SQL Saturday Philadelphia — May 4

No sooner did I return from one SQL Saturday that I discovered that I will be speaking at another! This morning, I learned that I will be speaking at Philadelphia on May 4! This will be the fourth time that I’ve spoken at Philadelphia SQL Saturday, and each one has been a good time!

I will be doing my presentation on technical writing and documentation!

If you are in southeastern Pennsylvania on May 4, register for SQL Saturday and come check it out! Hope to see you there!

SQL Saturday Virginia Beach — I’m speaking June 8!

I just found out today that I will be speaking at SQL Saturday #839, Virginia Beach on June 8!

I will be doing my presentation about the role of documentation in disaster recovery!

I’ll post about this event again as we get closer to the date. See you there in early June!

Don’t forget to edit your system messages

One of my current work projects is a administrative guide for our application. After a recent status meeting, one of the developers sent me a list of validation error messages that might appear during data imports. I was asked to make sure the validation messages were included with the documentation.

While going through the validation messages, I noticed that they were filled with grammatical, capitalization, and spelling errors. I asked the developer if he wanted me to edit the messages, to which he responded, “yes, please!”

People don’t think about checking output messages for correctness during application development. It is often a part of applications that is overlooked. For what it’s worth, I, myself, didn’t even think about it until I was asked about these validations. Nevertheless, reviewing and editing output messages is probably a pretty good idea.

For one thing, and I’ve stated this before, good writing reflects upon your organization. Well-written documentation can be indicative that a company cares enough about their product and their reputation that they make the effort to produce quality documentation as well. Well-written system messages indicate that you care enough to address even the little things.

Well-written error messages can also ensure better application usage and UX. A good output message can direct an end user to properly use the application or make any needed adjustments. Messages that are confusing, misleading, badly-written, or ambiguous could potentially result in things like application misuse, corrupted data, accidental security breaches, and user frustration.

Ensure your application development review and testing also includes a review of your system messages. It may be a small thing, but it could potentially address a number of issues. As someone once said, it’s the little things that count.

Dont rite so gud? Don’t let that stop you

Eye no that a Lot of ppl dont Right to gud. That shudnt keep ppl frum Riteing. Lot’s of ppl dont Right gud.

Did you have trouble reading that paragraph above? I actually had trouble writing it. The late Harry Chapin had a song called Six String Orchestra in which he intentionally plays badly. I once said that if you’re an accomplished musician, one of the most difficult things to do is to intentionally play something badly. If you’re a writer, I suppose the same is true for intentionally writing something badly. I remember reading a novel, Flowers for Algernon, in which a mentally-retarded man, writing in the first person, increases his intelligence after an operation. It was interesting reading the account as his intelligence and his awareness increased, and I can only imagine as to how challenging it might have been to write.

Anyway, in my technical writing presentation, one of the points I try to make is that not being able to write well should not discourage people from contributing to documentation.

I’m the first to admit that I’m a grammar snob. I’ll often be that person who is “silently correcting your grammar.” I cringe anytime someone doesn’t know the difference between “your” and “you’re.” I have to hide my eyes anytime someone uses an apostrophe-S as a plural. And I still believe that anyone who says “irregardless” should be flogged.

That said, I understand that not everyone is a good writer. Just because someone does not write well doesn’t mean that person should be discouraged from writing.

For one thing, as I said before, everyone has to start somewhere. Someone once said that “one of the dumbest quotes ever coined is ‘do it right the first time.’ It’s almost NEVER done right the first time.” And the one sure-fire method to improve is to practice. The more you write, the better you’ll get.

If I had to offer a piece of advice to someone who wanted to get better at writing, I’d suggest reading material by your favorite author, then try emulating that author’s style. For example, a few of my favorite authors include Stephen King, Tom Clancy, and Terry Brooks. I enjoy their books and their writing style. After reading their works, I found myself wanting to emulate how they write. I discovered that, over time, my writing kept getting better.

For another thing, an inability to write well doesn’t mean a person lacks intelligence or knowledge in a subject. That person often contributes to documentation as a subject-matter expert (SME). An SME has a great deal to contribute, but knowledge transfer can be challenging. To be fair, this is not an easy thing to do; one of the most difficult tasks is to communicate knowledge to other people. (I even have an entire presentation about this.) People often have valuable information to contribute; the challenge lies in how to convey that information. If someone with information doesn’t write well, that shouldn’t stop him or her from doing so.

Granted, if a piece of writing needs to convey a “good face” (say, client documentation or marketing materials, for example), then it’s important for it to be well-written. But if it’s a mere matter of knowledge transfer, it’s more important that a concept is written down rather than not be written at all. If an idea needs to be cleaned up, go ahead and write it down, and let someone else do the grammatical heavy-lifting. Not being a good writer should not be an impediment to writing at all.

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.