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.
Discussion on:
View:
Show:
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?
Pecos, I believe there are ISO or ? standards for technical docs. do you know where i could find that?
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.
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.
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
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
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.
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.
#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
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
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.
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.
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.
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.
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.
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.
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.
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.
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.
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
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
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.
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.
"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.
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.
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?
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?
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.
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.
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.
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.
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.
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.
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.
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.
"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.
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.
... 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."
nice to consider when we make the documentation - but some tips are seems to be not practical
Hi Raja,
Would you care to list the tips that are not practical. What makes them not practical in your work environment?
Would you care to list the tips that are not practical. What makes them not practical in your work environment?
I document everything I do. I won't remember what I did yesterday let alone six months ago.
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.
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.
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.
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.
- Keyboard Shortcuts:
- Prev
- Next
- Toggle
