Windows

10 things you can do to create better documentation


This blog entry is also available as a PDF from the TechRepublic download library.

Let's be honest. No one wants to write about it, read about it, or actually have to do it. I'm talking about documentation, usually defined as the second-to-last step in the Project Life Cycle. Although documentation can and should occur at any point in the Project Life Cycle, I will be focusing my tips on the documentation phase. Please note that there are two subsets of documentation I will be discussing, End User Documentation and System/Internal Documentation.

The Project Life Cycle

While doing the research for this article, I pulled out the Encyclopedia of Computer Science, editors Anthony Ralston and Chester L. Meek, Petrocelli/Charter, 1976. It is definitely a first edition classic, but some things are timeless. It states in the Documentation listing:

"Documentation is a vital part of developing and using a computer-based system. In some commercial organizations, 20 to 40% of the total development effort goes into the documentation of the new system, recording how the new system is to work and how it was developed." Author, K.R. London

I was curious if that was still true today, and if so, why documentation is not given the media coverage it deserves. I could not find a lot of information on the costs of documentation during the Project Life Cycle. (See Figure A.) I suspect that these costs are often understated or not properly collected. For IT professionals whose job is to develop working systems, many may consider admitting the actual costs of documentation as embarrassing or reflecting poorly on their productivity and work.

Your opinion of the documentation phase of the Project Life Cycle likely depends on your role in the IT organization. If you are a manager or project lead, documentation is critical to the success of the project. If you are in a non-managerial position, documentation is an annoying nuisance that gets in the way of your real work. While the 10 tips below are mainly targeted toward the latter category, managers and supervisors can also benefit from them.

Figure A

Source for the seven Project Life Cycle steps: WikipediA

#1: Document with pictures if possible

The old adage a picture is worth a thousand words means that by using pictures to augment your text, you can minimize the length and complexity of your documentation. System users like having pictures, diagrams, tables, and bulleted lists for quick reference.

#2: Give examples

Examples are an excellent way for end users to quickly grasp concepts that they may not fully understand. It is also a good way for an end user learning new software to sit down and tackle a new challenge more easily. Here is an example of documentation with pictures:

Previous Versions in Vista Business, Ultimate, and Enterprise

Previous Versions is the term that Microsoft uses for saving shadow copies of a file. If you are working on a document or any other project that is labor intensive and have accidentally lost part or all of your work, you can go back to a previous version. Think of it as an automated way to make snapshots of how the file looked at previous points in time.

But first you will have to configure Vista so that Previous Versions (Figures B through E) will be turned on for the logical drives/partitions that you want the ability to restore the previous versions of your files.

Enabling Previous Versions

Figure B

Select Start | Control Panel

Figure C

Left click Advanced system settings -- Left click Continue if prompted by the UAC (User Account Control)

Figure D

Left-click on the System Protection tab
NOTE: The Vista logical drive/partition is already enabled by default. Change this setting only if you fully understand the consequences of doing so.

Figure E

Scroll down and check logical drive

Left-click on the scroll bar and scroll down through the logical drives/partitions until you find the one for which you want to enable Previous Versions. That logical drive name is Documents in this example. Left-click the check box next to the logical drive name.

NOTE: Shadow copies are created based on the time and frequency of system created restore points. According to the Vista help file, this is typically once a day.

Left-click Apply and then left-click OK to close the System Properties window. Left-click File | Close or left-click on the red X box in the upper-right part of the Control Panel | System window to close it.

To restore the previous version of a file, you can right-click on the filename in Explorer and left-click Restore previous versions.

NOTE: Once a shadow copy of a file has been restored, it is no longer available for a second restore. Another shadow copy will not be created until the next system restore point is created. This means that any files saved before the next system restore point cannot be restored to the same previous version you used previously. Caution should be exercised saving files after using the Restore Previous Versions option until the next restore point occurs and another shadow copy can be created.

#3: Don't presume to assume

Even if you know your targeted user base, your documentation needs to be written so that anyone with only basic computer skills can read it and learn how to properly use the system. Step-by-step instructions should be provided when possible, but consider placing them in an appendix, a separate chapter, or making them available via a hyperlink to avoid clutter. If you are doing the documentation, change your mindset so that you place yourself in the shoes of a new system user. That can be difficult to do at first, but if you pay attention to details and fully document all features and functions, you can create documentation that doesn't assume that the user can figure out information and procedures you have failed to include.

Don't assume that your end user understands all of those acronyms that litter the IT landscape. The first time you present a new acronym, detail what the acronym stands for.

#4: Anticipate problems

When testing your system, you should have tried your best to break the software any way you could. If your software has known issues (developers like to call them issues; end users call them bugs), document a workaround and provide it to your users and the help desk. You will not only save a lot of frustration for the end users but also a lot of extra calls to the help desk.

Document the events that are inevitable during the lifetime of any long-lived system:

  • What workarounds are available while the system or network is down?
  • How do you recover from a server outage, a hard disk crash, or database corruption?
  • How does someone who knows absolutely nothing about your system get the system up and running again?

Your documentation should anticipate these problems and provide a detailed plan and instructions for system recovery.

Will the person who replaces you know where to find your documentation and any purchased vendor application documentation? All of these documents should be neatly organized and stored together in a safe and known place.

Another good example of anticipating problems is the Y2K Millennium Bug problem and solution. The media began reporting in the late 1990s that systems and software were likely to fail due to the storage of only two digits for the year in legacy systems. This problem was anticipated in advance and a lot of effort went into fixing the problem before it occurred. Software in development was built and certified as Y2K compliant years in advance of January 1, 2000. The results were remarkably successful. Except for a few minor reported problems, New Year's Day 2000 was a festive occasion and not a disaster for the IT community, though a lot of us were on-call just in case.

The same mindset can be used to anticipate problems that might arise in your documentation. The Y2K problem also illustrates the need for continual document updating. System/Internal Documentation was changed to note the Y2K compliance or noncompliance of software and systems. For older legacy systems, workarounds were found and documented.

#5: Test your documentation

Sit down and follow your own instructions. If you are documenting the building of a server, a network, or any other IT system, start with a clean partition and build everything from scratch. You will undoubtedly discover that you have left something out or that some of your instructions are unclear.

Work with an uninformed but committed co-worker to get feedback before you publish. Let them test out your documentation.

You will be amazed at what you will learn when you sit a person down to work with your software and documentation for the first time. A lot of features of the software that are obvious to you will not be so obvious to someone who is honest and willing to work with you. Watch closely what your guinea pig does while navigating your software. Ask for feedback and take notes.

I remember the feedback I got during the testing of one of my projects. The feedback was written in an e-mail so I could review it point by point. The first thought that came to mind was "how long will this take to do?" You may also take these comments as critical or personal. Don't make that mistake. Looking back on it now, I should have implemented more of the missing features that my helpful critic had provided.

Use this opportunity to make final tweaks to your project. Feedback during the documentation process can help you make the overall project more successful.

I was writing a review for the Foxconn 975X7AB-8EKRS2H motherboard and I ran across two errors in the manual. I wasn't the first person to review the board. Foxconn had missed the errors and all of the other reviewers had missed the errors as well. One mistake in the manual was far from trivial.

The diagram in the manual showing the normal position of the clear CMOS jumper setting was incorrect. I know because when turning the motherboard over to verify the proper seating of the heatsink, the jumper fell off. I put the jumper back on according to the instructions in the manual. The computer failed to POST. After a careful look at the tiny diagram on the motherboard, I discovered the error and corrected the misplaced jumper.

I was working with a tech from Foxconn at the time who was kind enough to answer my questions and I informed him of the error. Documentation errors like this are easy to miss and can lead to potentially large costs to the manufacturer. I would have missed the error myself were it not for the fact that the jumper had been loose enough to fall off when turning the motherboard over.

#6: Humanize your work

How many times have you read a user manual and wondered if there really was a human at the other end of the creation of the manual -- or was it a computer that made that manual? Although you don't want to create a colorful novel, humanize the document just enough with some of your personality so that a reader will feel a little more comfortable while reading it.

#7: Explore new technologies

Documentation can be costly even when done correctly. New technologies will continue to be created to help create more effective documentation that is less costly to develop. Look at these new tools as opportunities to reduce the time and cost of the documentation process.

Documenting as part of a project team can be especially difficult. Your documentation needs to be shared and added to the documentation of other team members. Changes have to be made, often on a daily basis. Software exists that will allow for this and will not only help to ensure a standardized end product but will also help to foster the sharing of ideas and knowledge among the team members.

While working at CSC (Computer Sciences Corporation) I had experimented with Microsoft's Agent and text-to-speech technology with mixed results. I always thought that it offered some wonderful ways to guide a new user through some of the features of my system. Some may remember that offensive little paper clip character with the blinking eyes in Word 97. It was slightly more than annoying.

With Agent, you can have your character move across the screen, point to a drop-down box, programmatically open the drop-down box, and allow the character to speak to you about the options presented. I created a guided tour of my software and let Peedy, the parrot, point to boxes, fill in text boxes, change screens, and generally walk the end user through the entire process of creating a new record in the database.

I found that using Agent saved me from having to write many tedious pages of documentation that detailed the steps necessary to create, save, and modify new records. It was also fun to develop. It allowed my creative side to participate in a positive and beneficial way. Creativity is pre-programmed in most developers and is a key component of what makes them successful. Creativity can and should be considered when developing your documentation, depending on the standards and expectations of your company.

The only feedback I received about my MS Agent experiment was that someone had too much time on their hands and it was never taken seriously, at least in part because of the comical looking character. It wasn't a lot of extra work to build, but it did require me to learn some new coding techniques. It was a pleasure when a person in our department was to be trained. I told them to take the guided tour. Perhaps Microsoft was ahead of its time, and with a more respectable character, this type of technology could still become mainstream one day.

I recently built a computer for my dad as a 50th wedding anniversary gift. I documented some notes marked Important PC Notes PLEASE Read and left a shortcut on the desktop. I also created an audio file that documented the features and use of the computer. I had to ask him if he looked at my notes, but he offered to tell me that he took the case and computer audio tour.

These are just a few examples of alternative ways to document. It is this humble writer's opinion that new ways to document are underutilized and underestimated for their simplicity and potential impact in today's corporate environment.

The elusive be all and end all documentation software package has yet to be developed, but there are a number of useful documentation tools that are designed for specific documentation tasks.

#8: Do the documentation yourself if possible

The best person to document is the builder. After all, who knows the system better than the system builder?

If you are the system builder, you are likely a crack programmer. But just mention the word document to a programmer and you will be given that "you've got to be kidding" look. If forced, programmers will document their work, or at least make an attempt to create something that will pass as documentation. I know. I have seen it all too often and even been guilty of it myself.

And that is a real shame because a programmer with good documentation skills is a valuable asset to the company. What will your manager remember at performance review time if another person had to do the documentation for your project? My guess is it won't be that you deserve a promotion, raise, or bonus.

While not exactly fun, documentation can be rewarding when done correctly. Not only will you have a better overall project to present to your customer, you will also greatly reduce the future support time you will have to provide. You can also reduce the amount of support and maintenance time for the help desk.

When working at CSC, I was given the opportunity to be the project lead for the design and creation of our global reporting system and infrastructure. I got to see first hand the other side of documentation. We had a very good programmer in the group who was doing Crystal Reports API work and custom function building. It was obvious to me that his knowledge was unique to him and needed to be shared with the rest of the team, and what better way to do that than to properly document his work? I wasn't entirely successful in getting him to explain his work to the point that another person could step in and pick it up. He did list and explain the function names, how to use them, how they worked, and what they accomplished, and that was very helpful to the other members of the team.

There seems to be an unwritten rule in the Realm of the Code that programming skills are inversely proportional to the amount of documentation programmers have to do.

The second greatest compliment ever paid to me in my career was when I had to give a presentation to our global technical support team. I had to create and present documentation on how to build a reporting server. One of our database administrators was a chap from England who had to sit in on the presentation. He looked at the How to Build a Reporting Sever document and, to paraphrase, commented how good the documentation was and that he should be able to build a reporting server using my documentation. Statements like that make all of the hard work worth it. And it wasn't a compliment for the main project work -- it was for the documentation.

#9: Coordinate the development of the End User Documentation with the Internal/System Documentation

You can cut your documentation time if you build your User Documentation at the same time you write the System Documentation. You can share some of the information between the two and reduce missing information. Even if you don't want to or it is inappropriate to share information between the documents, you can benefit from topics in one document that will prompt you to include additional documentation in the other.

#10: Follow department or corporate documentation guidelines

Create and follow standard formats and guidelines. This will help to ensure that important information is not excluded and allow for easier reading by system users.

The one time I had a dedicated documentation expert work with me to document my system was at Hughes Aircraft Company. The results were excellent. The format was the department standard and the results were better than I would have done. It required a lot of time and effort to get those results. The documentation expert needed access to my beta system and access to me so that I could answer questions. This is more expensive and not all companies have the resources to allocate to professional documentation, but the results can be excellent if the system builder can verify that important information is not misinterpreted or left out of the end product.

I was very fortunate that I had a former engineer who was also excellent at writing documentation. He understood what the system was designed and built to do and he filled in the blanks by actually using the system and discovering for himself how it worked. You may not be so fortunate.

In this day and age of global marketing, sales, and support, documentation should also follow country or regional standards. I am often irritated reading the manual for a piece of electronic gear made in China that is all too often difficult to translate. It is written in Chinglish and for some sentences I have to pause and try to comprehend. I usually just make a mental Scooby Doo sound and move on to the rest of the manual.

Were English-speaking documentation pros to learn (they never do) and write in Chinese, I imagine their Englese would sound the same to the Chinese-speaking people. Find and use a professional translator to make the documentation understandable so that important information is not lost in translation.

I should also state the obvious. Your documentation should be free of misspelling and grammatical errors. Always use a spell-checker to find errors. I never cease to be amazed at how many obvious spelling errors I have made and simply missed on a reread.

Documentation developer

If I haven't already convinced you that creating good documentation is good for you and your employer, take comfort in this fact -- creating good documentation is not just a menial task. When you document your work, you are now also a documentation developer. Hopefully these tips will help you to avoid those time-consuming and disruptive questions that are bound to come your way and to your friendly help desk techs.

Author's note:

This is my first officially published document. I want to personally thank Sonja Thompson and Mark Kaelin for giving me this opportunity to share my thoughts with you. I'm not sure why Mark decided to offer me the opportunity to discuss such a daunting subject as documentation for my first article. Perhaps he figured that if I could write an interesting article about documentation, I could write about almost anything! I am glad he did, though, and my thanks to him and TechRepublic are more than I can convey with the tools of this trade.

A gentle reader has become a gentle writer.

Additional references:

  • "...the four most important attributes about documentation include its content, maintenance, availability and use of examples." Page 58 of http://www.site.uottawa.ca/~tcl/gradtheses/aforward/aforward_thesis.doc
  • The importance of documentation: http://searchsmb.techtarget.com/originalContent/0,289142,sid44_gci1251087,00.html

About

Alan Norton began using PCs in 1981, when they were called microcomputers. He has worked at companies like Hughes Aircraft and CSC, where he developed client/server-based applications. Alan is currently semi-retired and starting a new career as a wri...

26 comments
BlueCollarCritic
BlueCollarCritic

Too often developers are in too much of a hurry to document and its not always tehir fault either. Many times they are under preassure from superiuos, on a tight time table that disallows for documentation. The attitude is often 'Whats important is getting itw orking, not writing a memoir about it".. And yes that is representative of supeiros attitudes towards documentation and thats because they aren't the ones who later on will need the documenatation because they aren't teh ones who have to revisit the code for changes at a later date. That being said developers have got to find time to document their work if not for tehir own benefit then for everyone elses. Even if you know you are not going to be at the same job when code review time comes you shoudl still work to document your work as if you were going to be the one neededing it. Justr imagine how much easier all developers jobs would be if everyone provided documentation of tehir work even at the moist basic level.

huntress
huntress

I document everything I do. I won't remember what I did yesterday let alone six months ago.

raja
raja

nice to consider when we make the documentation - but some tips are seems to be not practical

mmoran
mmoran

Alan writes: "Find and use a professional translator to make the documentation understandable so that important information is not lost in translation." Based on my own experience I would say "... a professional translator who understands the technology and the concepts that he/she is translating..." Complex technical concepts seldom enjoy a one-to-one terminology and vocabulary equivalence between source and target languages. The translator needs to have an understanding of the field sufficient to enable him/her to correctly and accurately convey and explain the concepts using, if necessary, multiple words and phrases in the target language. In coordinating the translation into Spanish of user manuals, training materials and other technical documentation for my company's products (automatic test equipment and instrumentation), I found that the results from the translation agencies that we initially used were in some cases nearly gibberish. Gramatically they were fine, but it was obvious that the translators had no command of the concepts or terminology involved. I wouldn't expect this to be the case for straightforward and "universal" computer/IT documentation, but ours is a highly specialized field. While Spanish is not my native language, I am a fluent non-native speaker and eventually chose to simply bring the translation tasks in-house, as it was taking as much time to correct the outside work as it would take to simply do it from the start. Whatever your specific field of technology, when commissioning professional translations of your documentation it's vital to interview the prospective translator beforehand, in much the same spirit as you would interview a prospective employee.

khicks
khicks

Documentation is crucial. I can never understand why an IT person spends hours figuring something out, then doesn't document it. The same issue comes up a year later and because it wasn't documented, they spend more hours figuring it out. If you get in the habit of documentation, it is really easy. Great article.

Alan Norton
Alan Norton

Or maybe you like the documentation process. Are these tips helpful to you? Grade my work. I would like to hear your documentation stories. Any and all feedback welcomed. I will be checking in to participate and answer any questions you might have.

Alan Norton
Alan Norton

I have the same problem. :-) I had one development position where I could, for the most part, manage my own time and work. I learned early-on that documenting my work was in my own self interest. I always wanted to move on to the next project without interruptions and the best way to do that was to point the users to the documentation when they had some questions.

Alan Norton
Alan Norton

Hi Raja, Would you care to list the tips that are not practical. What makes them not practical in your work environment?

Alan Norton
Alan Norton

Thank you for sharing your experiences. I wonder if your careful attention to properly translated manuals is the exception and not the rule. I have been learning about the hardware world and have recently built three PC's. The manuals included with Chinese products have often been translated or written in English in such a way that they are difficult to decipher. With the Internet available worldwide it would seem to me to be easy for an English speaking, technically savvy person to preview the documentation and submit any revisions. Why isn't it done? There are a lot of retired or semi-retired tech people that would be glad to review the manuals for little compensation. It sounds like there is a small business opportunity there somewhere. The software based translation programs are simply horrible - especially for technical material.

Alan Norton
Alan Norton

You are right. Documentation saves time in the maintenance phase of the project life cycle. It is pay me now or pay me later. Like any learned skill that requires some effort, it does become easier after a little practice. I can only speak for what I have seen, but I have experienced three primary reasons for system builders and programmers not creating good documentation. The first is that they are insecure about their job and want to keep the information to themselves. They believe their unique knowledge to be (arguably incorrectly) a form of job security. They tend to be junior programmers or even more senior IT professionals in an environment of downsizing. I was hired into my first major IT position with another person. It appeared obvious to me that only one of us would be working there after a year. Talk about stress! I literally lost my hair. Is it any wonder that employees in this position tend to hoard their knowledge and fail to document their work? The other reason that I have seen is simply that documentation is a lot of work for no immediate gain. Documentation is no fun when you are a creative system builder. There is little or no creativity in the documentation process. That is just one reason why I feel more creative ways to develop documentation could be very successful. The third reason is that system builders may not be experienced enough to know the importance of documentation and/or they may not be required to fully document the system. Thank you for the kind words and feedback.

SnoopDougEDoug
SnoopDougEDoug

#1 Hire a pro! As you can probably guess, I am one such pro. I've been doing technical documentation for over 20 years. I agree on most of his points, but my experience has been that if developers hate writing documentation and you force them to do so, the docs will suck. There is no way a dev is going to produce better docs than a professional writer. I take that back. In my 20 years of technical writing, I have come across one developer who wrote great docs. The other 99 were extremely grateful for my help. Developers should expect to provide some level of information. I would settle for structured comments, such as JavaDoc, in the source that I could compile. All I would ask is that the devs keep the comments current. Although I've worked on more than one project where the comments rapidly became irrelevant, it is better than nothing. I also pride myself on figuring a lot of issue out by reading the source, so I provide a second set of eyes confirming the comments. There is also a huge difference between system/internal docs and external docs. External docs should look at the system as a black box. Internal docs should point out all of the warts. If you do hire a pro, #2 would be "Bring them on board early". Even the smartest person takes some time to come up to speed. I know it's expensive, but the alternative is crummy docs. doug in Seattle

Alan Norton
Alan Norton

I remembered some additional information that I should have included in the documentation example. Since the official documentation has been released this would be considered the maintenance phase of the project life cycle. Change History: Title: 10 things you can do to create better documentation Changed By: Alan Norton Date: July 20, 2007 Change: Changed the documentation example. Added which versions of Vista that Previous Versions is available. ADDENDUM NOTE: The Previous Versions feature is only available in the Business, Ultimate and Enterprise versions of Vista.

sgt_shultz
sgt_shultz

is all i'd add. it is difficult to write documentation to make everybody happy so i try to learn who i am writing for. Pecos, I believe there are ISO or ? standards for technical docs. do you know where i could find that?

mmoran
mmoran

Well, my own love of the Spanish language was one factor, but probably the bigger one was the fact that our customer had plants in Mexico and was paying to have the manuals translated, so my time could be justified from a business standpoint. I imagine that the reason your Chinese hardware manuals have been poorly translated is the same as what you touched on in the article... documentation is viewed as an afterthought and an annoyance. In the case of price-sensitive consumer products like PC components, nobody is going to pay for a translation to be checked and edited by a technically-knowledgeable native speaker. Hence we get the "Chinenglish." Funny example from back in the Pentium-100 days: the concluding sentence in the manual for a Taiwan-produced motherboard probably meant to convey something like "Enjoy your new motherboard!" What it actually said was "Be happy with what you got." For the most part, agreed on the software translation programs, although they have improved dramatically over the years and the higher-quality ones are now quite serviceable for "gist" translation of non-technical documents in other languages, although you still wouldn't use them to translate formal business documents from English into another language. About ten years ago I tried what was at the time one of the more highly-touted programs on a document intended to guide a technican through replacing the obsolete hard drive of an industrial computer. At the point where the reader was instructed to use a washer, the program translated "washer" as "lavadora" rather than "arandela," thereby instructing the Spanish-speaking user to place a washing machine between the slightly smaller new drive and the mounting rail. Personally I use Word Magic Tools (www.wordmagicsoft.com) in the "computer-assisted translation" mode rather than on full automatic, and find that it offers substantial productivity gains that way.

manan123
manan123

Hello All... I have been doing technical documenting for applications, Designed and implemented the ISO 9001 and 27001 standard in my 1 year in this field. As part of the standard, documentation is mandatory. still i observed that very few (or almost none) actually likes to document their work. Few reasons i was able to figure out are: 1) Job hopping is one major reason. people know they will be with some other company after 1 year or so. so they are never going to get the benefits of documentation (which comes during maintenance). 2) secondly, they feel documentation is a overhead. Writing is not a simple job especially when someone is weak in communication. so ignorance is masked with the overhead tag. 3) lastly, lack of standards. strict work instruction that includes documentation will help. management directive of "compulsory documentation" aligned with the appraisal will help. Let me have your thoughts on this.

dkenny
dkenny

It depends how robust your IT Team is, and how much time you have at your disposal. If you have an IT department of 3 people to support 1,000 staff and 10,000 students spread over 11 sites, I can tell you from experience that documentation nearly always falls by the wayside, in favor of quelling other user/network problems. I don't debate your point. Documentation *IS* important, long-term. The sad fact is that documentation is never as important as putting out fires. What little documentation I get done, gets done at home, or at work after hours.

SnoopDougEDoug
SnoopDougEDoug

This step is called "audience analysis" is the profession. Technical documentation must be: * Accurate * Complete * Appropriate (your point) If it is not accurate (and readers can be vicious about even the most innocuous typo or misspelling), you lose the reader. Completeness is relative and depends on your time, your audience's expectations and knowledge of the product, and time. Technical documentation is typically constructed bottom-up. First the reference section, then any guide/how-to info, next installation instructions, and finally, if there is time, a tutorial. The trick to the middle section is finding the sweet spot between a useless example and coverage of the "most crucial" topics. doug

Alan Norton
Alan Norton

I found two ISO/IEC standards for sofware/systems/project life cycle: ISO/IEC 12207 ISO/IEC 15289 Google them for a list of sites. Most sites charge for the docs. If that isn't what you mean by technical docs, let me know exactly what kind of technical docs you are talking about. Happy reading.

mmoran
mmoran

... about the first impressions. If I run into problems with a newly-purchased tech toy, the quality of the documentation always has a big influence on whether my response is "Now, what did I screw up?" vs. "This P.O.S. is going back to the store."

Alan Norton
Alan Norton

"Funny example from back in the Pentium-100 days: the concluding sentence in the manual for a Taiwan-produced motherboard probably meant to convey something like "Enjoy your new motherboard!" What it actually said was "Be happy with what you got."" That's a classic. I'll have to remember that one! First impressions are important. If the first thing a person looks at when he/she opens up their new hardware or software box is a manual that is hard to comprehend, they may wonder what other details have been overlooked. I have been trying to find a working Intel 537EP modem driver for Kubuntu Feisty Fawn and was trying out Google's translation feature. I could get the gist of the discussion like you say, but some of the words were wrong to the point of being just as funny as your great examples.

Alan Norton
Alan Norton

I would imagine that it would be next to impossible to find budget for documenting legacy apps. Outsourcing the documentation of current and future projects could be quite successful once developers understand it is in their best interest. Outsourcing is a bad word in the states if you happen to be in a position that could be outsourced. I doubt though if you would find much objection to outsourcing the kind of jobs that you are talking about. I can tell you this. I wouldn't want and didn't want the job of documenting legacy apps. I had no problem documenting my projects since I knew it was the best way to move on to another project without those annoying interruptions. But I also had no problem letting one of our technical documenters do the work for me either. Yes, it's good to see interest in documentation and thank you for your participation.

manan123
manan123

Hello All good to see the participation. Like we all agree that documentation is required but still nobody executes effectively. I was wondering if there are companies who outsource their documenting jobs. companies can get their legacy applications (undocumented for sure) documented and preserve their business logic for future developments. Any idea / experience about this topic?

Alan Norton
Alan Norton

Your mechanic analogy reminds me of some commercials a few years back for a brand of motor oil. "Pay me now or pay me later" the commercial said. It's the same way with documentation. The shops where I get my truck fixed keep the mechanics far away from the customers. It is usually the shop managers job to communicate the work needed with the customer. IT techs don't have this luxury. They are usually working directly with the customer so good verbal communication skills are important. Developers have less direct contact. Good written communication skills are important for them since their documentation and help files are there for the end user when they can't be. Thank you for your comments.

Alan Norton
Alan Norton

"1) Job hopping is one major reason. people know they will be with some other company after 1 year or so. so they are never going to get the benefits of documentation (which comes during maintenance)." A true professional would do the job correctly whether they benefited or not. You are right though. Job hopping is a real problem since those who change jobs frequently do not think they will be around in a few years and have no incentive to do the proper documentation. This kind of 'professional' who job hops may find him or herself in a position where they have to support a system that has poor documentation. They will then discover the hard way just how important documentation really is. "2) secondly, they feel documentation is a overhead. Writing is not a simple job especially when someone is weak in communication. so ignorance is masked with the overhead tag." Writing skills can be learned if they haven't been already. Management support is crucial in my opinion to foster proper communication and writing skills. The overhead tag is an unfortunate reality in a world with short term thinking and goals drive the bottom line. Good documentation is an investment in the future. I have been fortunate to work in companies who understand this concept, but there were pockets of IT groups that had little or no documentation and were headed for maintenance only 'fire-fighting' mode. I tried hard to avoid those groups since I find maintenance even more painful than documentation. "3) lastly, lack of standards. strict work instruction that includes documentation will help. management directive of "compulsory documentation" aligned with the appraisal will help." Excellent points. Standards are a framework for the start of good documentation. Management can support good documentation with emphasis on the process and tangible incentives.

dkenny
dkenny

I agree that most techs seem to have low communications skills (or, at least pointedly lower than their problem-solving skills). It's also difficult to escape the language barrier between users and developers/techs. My experience is that developers/techs know what they know at a gut level. Many of them can't verbalize what they know, why they know it, or how long what they know took them to learn. My belief is developers/techs have honed their abilities to rapidly assimilate new knowledge into the patterns of what they already know. Because the developer/tech knowledge is vastly larger than the users, and more specialized to the unseen underpinnings of how systems work, it's honestly quite difficult to perceive where users are going to have problems. The situation reminds me of my own communications with my car mechanic. I know nothing about cars, and I'm sure the mechanics laugh (and/or grumble) about my lack of ability to accurately describe my problems. At the same time, their skills makes them good at fixing my problems but not necessarily as good at communicating with me. Granted operation of a car has nowhere near the complexity of interaction with a computer, but you get the gist. David

Alan Norton
Alan Norton

The big problems come when the developer/systems expert leaves or is unavailable. Then a small number of fires can become infernos if good documentation is not available. Woe be to the poor IT recruit who has to go in to put out those fires. For an IT department staff that ends up in this situation, it can be very frustrating and demoralizing. Once there, it can be almost impossible to not be in constant fire-fighting mode. But you are right. With insufficient resources, keeping your users happy and up and running becomes the first priority.

Editor's Picks