|
Latest Articles
|
|
Documentation is not a Four Letter Word |
|
Written by Andrew Kass
|
 When I had first started working in the Information Technology world, I innocently asked my boss how to use some legacy software used by the enterprise for which I worked. I was told, “RTFM.” I pretended I knew what that meant and sulked away to try and find out the meaning of that acronym. It was before the advent of the internet, so it took me awhile to determine the true meaning. To borrow from the Christmas Classic, “A Christmas Story,” I learned it meant, “Read the Fudging Manual.” Only my boss didn’t mean “Fudge.”
Nothing seems to inspire the wrath of the common business worker as the topic of documentation. No one likes to read it. And because of that no one likes to write it. It is hard to blame people for not reading documentation. When is the last time you picked up a user manual? It’s probably been awhile. No one even prints documentation anymore. You can maybe find an odd PDF file here or there, and then you have two choices: you can print it out and kill a few trees at your own expense, or you can read it online. Most people don’t do either.
But at the root of the reason that people don’t read documentation is the fact that it is often so poorly written. When people turn to a resource for answers, and that resource fails to provide them with the information for which they are looking, they quickly will turn against it, and stop relying on it as a resource for their needs. People, especially those who write documentation, are always quick to blame those that read the documentation. But what writers don’t understand is that when people don’t read documentation, it’s as much a reflection on themselves as a writer as it is on the reader.
That’s where the Business Analyst comes in. The role of the Business Analyst, at its core, is the role of a communicator. The Business Analyst is bi-lingual; the BA acts as a translator. The BA speaks the language of Business and of Technology. Each language has many dialects, colloquialisms, and subtle slang in its vernacular. When communicated verbally, this information and its associated subtleties can be picked up in body language or intonation, but when formally documented, the deliverable must be clear and concise, and leave little room for interpretation. When a BA writes documentation, it needs to command not only the attention, but the respect of its audience.
So how do you write documentation that people want to read?
As a Business Analyst, the following approaches and techniques will help you assemble compelling documentation:
Balance Style and Substance in Your Documentation
No one wants to read ugly documentation. Appearances make a big difference. You can write up the best requirements and use cases but no one will ever know if they choose not to read it. Be consistent in your formatting, font choice and organizational flow.
Now all of that being said, you can only briefly fool someone into reading nicely dressed-up garbage. Obviously, things like spelling and grammar are a given—and most importantly make sure your content is accurate. You will quickly lose credibility if your use cases don’t even accurately align with the interfaces that the development team is building. The substance of your documentation is more important than its appearance, but like that nice guy or gal you fell in love with, you probably didn’t notice them first for their winning personality. Give your book a good cover if you want people to open it.
Put Microsoft Word to Work for You
I say Microsoft Word, but whatever software you use, make sure you have the software do the heavy lifting. It will help you establish the appropriate style and structure for your documentation if you employ features like stylesheets, tables of contents, templates, and master documents.
Something as simple as structuring your headings and subheadings with the appropriate style names will create consistency in the appearance of your documentation, but more importantly it will allow Word to automatically hierarchically number and organize your document and automatically generate a table of contents for your document. Again, not only are these powerful features that make your job easier, but they create a consistent look and style for your documentation.
I mentioned master documents. Master documents are a fairly advanced technique that I encourage everyone to investigate. Master documents are a way of embedding references from other Word documents into a single Word document. A great way of thinking about and implementing master documents is in conjunction with use cases. Every use case you document can be its own Word document. These individual use cases can then be embedded into master documents. A single use case can be embedded in multiple master documents. Then, when the use case is updated in a single location, those changes automatically appear in every document in which that use case is documented. Using this technique, you can create a Release Design Document and a Functional Design Document with little additional effort. As a result, you don’t need to be concerned about maintaining redundant content in multiple documents; while at the same time, you can deliver precise content to your audience for whatever need you might have.
Create a Document Platform and Strategy
There is no one right way to prepare documentation. There are definitely wrong ways, but no singular correct way of doing things. But perhaps the best advice of all is to prove out what approach works for your organization and stick to it. And do more than just talk about what worked. Do more than keep copies of documentation from legendary projects gone by.
Start by implementing a documentation management system. You can use commercial solutions like SharePoint or Quickr. Or you can leverage existing technologies utilized by the development team for source control. Or keep it simple; use a simple network folder structure design. There are many benefits to be gained from using any of these solutions. Ranging from version control, to automated team notification, to workflow, to approvals, to audit, to security and backup.
And not to be understated, perhaps the greatest value of a documentation platform is adoption. Implementing an established go-to repository of documentation for a project is invaluable. When you are trying to encourage readers to utilize documentation, one of the greatest crutches for a user is to go to the source. As many a Business Analyst has come to learn, all too often, they are the source. The old adage “Give a man a fish, he’ll eat for a day. Teach a man to fish, you’ll feed him for a lifetime” quickly becomes true. As a BA, there can be nothing more frustrating than having someone ask you a question that you know you documented in great detail. You have your hands full getting the use cases written for the next release; you have better things to do than field questions from releases gone by. It almost makes you want to tell them to RTFM, doesn’t it?
Like a great help system or a valuable web-based search engine, your users will return again and again to an established, known, consistent, and polished repository for answers. In conjunction with techniques like master documentation and individualized use cases, it makes for a compelling interaction for your development team to consume the information that they need in a very granular manner.
Write Well
And finally there is no better way to guarantee that users will read your documentation than to write well. You have to write for various audiences on both the business and technology sides of the organization. Keeping such diverse audiences happy is not an easy task. Asking a person to write well is obvious advice, and more easily said than done, and unfortunately has been deemed out of scope of this document. With a change request, I could address that in a future release.
This article was inspired by a June presentation at BA World in Minneapolis by the author.
|
|
|
|
