Kuro5hin.org: technology and culture, from the trenches
create account | help/FAQ | contact | links | search | IRC | site news
[ Everything | Diaries | Technology | Science | Culture | Politics | Media | News | Internet | Op-Ed | Fiction | Meta | MLP ]
We need your support: buy an ad | premium membership

[P]
HOWTO: write bad documentation that looks good

By clover_kicker in Technology
Tue Sep 30, 2003 at 07:19:34 PM EST
Tags: Technology (all tags)
Technology

Intro

In every tech's life, there comes a time when management starts to insist on better documentation.

Perhaps a round of layoffs or outsourcing is imminent. Perhaps the simmering disdain between techs and management has escalated into open hatred. Either way, you are clearly on the way out, and management wants to grease the wheels for your successor.

Objectives

You wish to produce documentation that:

  • will impress your management, and facilitate your remaining time in that job.
  • will not substantially help your replacement(s).
  • does not betray obvious signs of sabotage.


General Principles
  • Writing good documentation is hard.
  • Your management does not understand how complicated the situation really is.
  • Your manager sincerely believes that more documentation is better.
  • As the amount of documentation increases, so does the effort required to maintain it.
  • To fully understand any situation, you need to know the 5 W's, i.e. Who, What, Where, When, and Why.
  • In general, documenting "what" is not nearly as valuable as documenting "how" and/or "why". "What" can be discovered with a little effort, but the reasons "why" are often obscure and complicated. Your most valuable asset in your current job might be your detailed understanding of why everything is set up the way it is.
  • Complex systems generally have several interdependent components. Often, the relationship between these components is a tricky affair, finely tuned after months or years of tweaking.
Concrete suggestions

More is not better

It is easy to produce impressive quantities of paper by documenting the very obvious and/or completely useless.

Spend lots of time on the appearance and presentation of your documentation. Your management is easily distracted by shiny things, and will not realize that your binders contain information that could easily be recreated by anyone.

Creating bad documentation is time consuming, and makes you look very busy. You can use your documentation as an excuse to avoid real work, or perhaps to con a few more days of employment.

One insidious consequence of overly detailed documentation is the maintenance required. Recording trivial changes is very time consuming. However, unmaintained documents quickly become inaccurate and misleading, arguably worse then no documentation at all.

Example 1

A sysadmin could make a binder for each server with serial #s, driver diskettes, partition images burnt onto CD, etc. Include lots of obvious hardware and software settings, i.e IRQs, driver revisions, patchlevels, IP addrs, MAC addrs, etc.

Routers and switches should also get a binder with appropriate h/w and configuration information.

A programmer might bulk up documentation with information about trivial internal functions and macros.

Never tell "why"

Never describe what problems you've encountered, or how you solved them.

Do not explain what task each program or machine is doing. Do not explain the interactions of any systems, or which programs/machines depend on other programs or machines.

A programmer should never call attention to global variables, or functions with side-effects.

Example 2

In the past, there have been problems with running out of a particular resource (disk/RAM/bandwidth/whatever) on a particular machine. You have written a script to help predict when this problem is about to occur.

do:
  • Document the existence of this script
  • Document what inputs the script requires
  • Document what output the script produces
do not:
  • Document what condition the script was written to detect, or the consequences of that condition.
extra credit:
  • Modify the script to examine additional machines and/or resources. This will help obscure the true purpose of the script.
  • Parameterize the script so that it can examine several different machines and/or resources. Make the default action something plausible but irrelevant, and manually provide sensible parameters when you invoke the script. If your script is a cron job, make it produce a few extra reports every day. The more automagic logs one receives, the less attention is paid to them.
An ounce of disorganization is worth a pound of confusion

You can achieve maddening results by carefully fragmenting your documentation.

A well-written "principles of operation" document that describes the big picture is worth a million pages of detailed trivia. Your "special" documentation should therefore meticulously detail the trees, while scrupulously ignoring the forest.

Example 3

Would it be more frustrating to learn Unix system administration by only reading man pages, or an overview which referred to specific man pages where appropriate?

Which would cause more grey hairs?

  • A network diagram listing all servers, and their IP addresses
  • A set of detailed documents, one per server. Each server document consistently records the IP address on page 13.

Which of these documents is worth the paper it is printed on?

  • A 1 page document listing all global variables
  • A large document with a detailed entry for each variable, listed alphabetically.

Theoretically, your trouble ticket system contains all the information you've been trying to obfuscate. In practice, all such systems exemplify the flaws we've discussed: poor organization, too much irrelevant detail and too little discussion of "why".

At best, your trouble ticket database is full of sketchy problem descriptions and meaninglessly vague resolution fields. More likely, the ticket database is an incoherent work of speculative fiction that doesn't contain records for many changes.

Afterword:

Most technical documentation suffers from the above flaws without even trying to be evil. Commercial software documentation is execrable, and in-house documentation is worse, especially when produced in accordance with a formalized documentation standard.

The above article is a satire meant to help you write good documentation. Honest.

Sponsors

Voxel dot net
o Managed Hosting
o VoxCAST Content Delivery
o Raw Infrastructure

Login

Poll
I have...
o never worked with documentation this bad 5%
o worked with documentation that was accidentally this bad 56%
o worked with documentation that was deliberately this bad 38%

Votes: 71
Results | Other Polls

Related Links
o Also by clover_kicker


Display: Sort:
HOWTO: write bad documentation that looks good | 83 comments (64 topical, 19 editorial, 0 hidden)
What's the point of posting it here (1.84 / 25) (#1)
by psychologist on Mon Sep 29, 2003 at 10:46:30 AM EST

Gnu hippies don't care about, or write documentation.

your trolling style (4.07 / 14) (#8)
by tps12 on Mon Sep 29, 2003 at 11:04:15 AM EST

That's like some 1998 shit right there man.

[ Parent ]
Don't worry (2.00 / 11) (#9)
by psychologist on Mon Sep 29, 2003 at 11:42:22 AM EST

Bookmark my diary and wait for the cutting edge shit.

[ Parent ]
It's a vintage classic. (3.77 / 9) (#13)
by tkatchev on Mon Sep 29, 2003 at 12:57:38 PM EST

In case you missed it the first fifty times it was beaten to death.

   -- Signed, Lev Andropoff, cosmonaut.
[ Parent ]

Calling "1998" is so 2001 (4.86 / 23) (#35)
by synaesthesia on Tue Sep 30, 2003 at 09:07:58 PM EST

And although calling "calling 1998 is so 2001" is kinda 2002, calling calling 1998 2001 2002 is fresh as fuck. Old is the new new.


Sausages or cheese?
[ Parent ]
Dude (4.50 / 4) (#42)
by Roman on Wed Oct 01, 2003 at 09:22:19 AM EST

You just got my vote, I don't know what the fuck you are saying, but it just sounds so beautiful!

:)

[ Parent ]
Is that trolling? (4.16 / 6) (#17)
by Tatarigami on Mon Sep 29, 2003 at 03:46:49 PM EST

You're just going through the motions. Don't you care about us anymore?

[ Parent ]
Info == evil cross of man+emacs+html (nt) (3.00 / 1) (#44)
by philwise on Wed Oct 01, 2003 at 09:41:09 AM EST


--
(presenter) "So, altogether now, what are we?"
(audience) "We are all Free Thinkers."
[ Parent ]
GNU documentation standards (2.50 / 2) (#49)
by pin0cchio on Wed Oct 01, 2003 at 11:59:59 AM EST

Gnu hippies don't care about, or write documentation.

What in GNU Coding Standards: Documentation seems wrong to you?


lj65
[ Parent ]
It's nice (4.14 / 14) (#10)
by glor on Mon Sep 29, 2003 at 12:27:29 PM EST

that you're following your own advice and writing bad documentation on writing bad documentation. Good show.

--
Disclaimer: I am not the most intelligent kuron.

Are you (4.71 / 7) (#34)
by synaesthesia on Tue Sep 30, 2003 at 09:02:25 PM EST

Satirically complimenting him? I'm confused :)

Sausages or cheese?
[ Parent ]
facilitating! (4.62 / 16) (#19)
by termv on Mon Sep 29, 2003 at 07:58:47 PM EST

I'm glad you said that! The tech writer at my company seems to think that the word facilitate is appropriately descriptive for various program features. It's the perfect word -- It describes WHAT you're doing (facilitating), WHY they would want to do it (to make it easier), and eliminates any need to understand what you're actually documenting.

Example:

The netmask field is used to facilitate the entry of your networking information.

You get bonus points if you include a screenshot with a helpful example (like www.yahoo.com) filled in.


Reminds me of a quote from an old boss... (4.55 / 9) (#24)
by the77x42 on Tue Sep 30, 2003 at 04:53:21 AM EST

"Don't worry about the documentation, we need this thing running yesterday!"

Well guess what, tomorrow it will be broken and no one will know what the fuck it is and rewrite it. Of course, he said the above quote on the third rewrite.


"We're not here to educate. We're here to point and laugh." - creature
"You have some pretty stupid ideas." - indubitable ‮

No they won't rewrite... (3.66 / 3) (#39)
by l3nz on Wed Oct 01, 2003 at 06:59:35 AM EST

They'll just hack up a patch of some sort without the least undertanding of how the thing works, and deploy it as soon as possible. It was due yesterday, wasn't it? :-)

Popk ToDo lists - yet another web-based ToDo list manager. 100% AJAX free :-)
[ Parent ]

I can beat that. (4.75 / 5) (#45)
by bakuretsu on Wed Oct 01, 2003 at 10:23:17 AM EST

"There is never time to do it right, but there's always time to do it over."

Ever heard THAT one? It's axiomatic, in a very idiotic way. I believe my boss actually said that once; he often uses time constraints as an excuse to disregard logic or testing.

-- Airborne
    aka Bakuretsu
    The Bailiwick -- DESIGNHUB 2004
[ Parent ]

A wise man once said to me... (4.50 / 12) (#25)
by gcmillwood on Tue Sep 30, 2003 at 09:22:17 AM EST

"A system that is being used gets modified.  A system that is not being used gets documented."

An unwise man once sent to me... (3.50 / 3) (#27)
by WeaponOfChoice on Tue Sep 30, 2003 at 12:39:48 PM EST

We once bought a package where the company felt the need to send us several spiral bound trees to "teach" our webmonkeys how to use it. Must have been 20,000 pages - so much of it absolutely useless (imagine a javadoc... printed... ???).

Strange times...

Be Strong: Protect the Weak.
[ Parent ]
Would that have been Oracle? (4.50 / 2) (#37)
by Christopher on Wed Oct 01, 2003 at 01:54:57 AM EST

They are the kings of this kind of documentation. I spent nearly a week digging through documentation on:
  1. The Java Application Server (Ora9iAS)
  2. Oracle's extensions of Apache
  3. Oracle's Web Cache
  4. Oracle Internet Directory
  5. Single Sign-On™
None of these documents mentioned the others, or how they were related. Now, several months later, I and my single fellow Java programmer have a hand-drawn diagram of how everything fits together. We have submitted a request to Oracle that they put our diagram on page one of every manual they produce on any of these things. (No response yet on that. We assume they're talking to their tech writers about getting it done.)

_______________________________
more and more to do, less and less to prove
[ Parent ]

Damn, you beat me to it. (4.10 / 10) (#26)
by Akshay on Tue Sep 30, 2003 at 11:58:14 AM EST

Was going to post an Op-Ed on the alarming bulletization of popular thought as a result of increasing prevalence of Microsoft PowerPoint.

+1 FP anyway. :-)

Damn, you beat me to the bulletization. (4.00 / 8) (#60)
by OzJuggler on Thu Oct 02, 2003 at 12:04:40 AM EST

I was going to post a comment about the alarming trend of creating complex mutant abstract nouns from perfectly ordinary verb phrases as a result of the increasing American influence on English.

But I participated in the fourization of your comment anyway. ;-D
"And I will not rest until every year families gather to spend December 25th together
at Osama's homo abortion pot and commie jizzporium." - Jon Stewart's gift to Bill O'Reilly, 7 Dec 2005.
[ Parent ]

Wish I'd had this a couple years ago... (3.77 / 9) (#31)
by Gooba42 on Tue Sep 30, 2003 at 07:30:24 PM EST

I was working at a medium company working hard to become a small company when they told me to document everything I did. The best part was when they took all previous documentation and threw it out before asking me to re-document the same process. Apparently they decided I was so successful at this that the laid someone else off, stuck me with his job and asked me to write the documentation there too, at the same time updating procedures and trying to pass ISO.

Mind you, at the time I had never written any kind of documentation before at all so having no example from which to template my work was oh so helpful, particularly when they stuck me with a new job and wanted me to write documentation, which I had never done before, to do a job I had also never done before.

Best Part (3.25 / 8) (#32)
by Katt on Tue Sep 30, 2003 at 07:47:18 PM EST

Your management is easily distracted by shiny things.

Maybe it's because I am also distracted by shiny things, but that was the best one-line quip in the article.

Education (3.50 / 6) (#33)
by virtualjay222 on Tue Sep 30, 2003 at 08:15:15 PM EST

I'm confused. Did the meaningless drivel required in the workplace result from the meaningless drivel taught in schools, or is it the other way around?

I mean, even my intro biology professor in college had us doing coloring books to learn different processes. Coloring Books?! If only I were kidding.

---

I'm not in denial, I'm just selective about the reality I choose to accept.

-Calvin and Hobbes


Let's apply this. (2.42 / 7) (#36)
by phlyingpenguin on Tue Sep 30, 2003 at 09:42:53 PM EST

Can I write Kuro5hin articles with the same technique?

There is no signature
hm (3.66 / 3) (#50)
by EMHMark3 on Wed Oct 01, 2003 at 12:06:56 PM EST

Have you ever looked at the edit queue? Yeah.

T H E   M A C H I N E   S T O P S
[ Parent ]

don't forget the company policy bullsh*t (4.36 / 11) (#38)
by m a r c on Wed Oct 01, 2003 at 03:13:59 AM EST

a great way to make your doco look a lot better than what it is without much extra work at all is to put in sections on proper procedures and policies which is already common knowledge, like SLAs. Usually the proecedures are already docuemented so its a cut and paste job. Just say you were trying to make the document self contained.
I got a dog and named him "Stay". Now, I go "Come here, Stay!". After a while, the dog went insane and wouldn't move at all.
good point (4.40 / 5) (#40)
by clover_kicker on Wed Oct 01, 2003 at 09:00:13 AM EST

You've just described the infamous "cut & paste maintenance time bomb".

If a policy is updated, is anyone going to remember how many documents it was cut+pasted into, and update them? Of course not.

Over a couple of years, your documentation becomes a twisty maze of cut'n'pasted procedures, all slightly different.

A few jobs ago, a co-worker took over maintenance of a particular program.

Every couple of days, he'd get too pissed off to work on it any more, and come rant at us about all the stupid problems with this app.

The biggest problem: the guy who wrote it was a firm believer in cut & paste. He apparently measured his self esteem in terms of how many klocs he wrote.

The original programmer *never* used subroutines. When he wanted to do something he had already written code for, he cut & pasted the relevant code from a different part of the app. Over time, some of these code blocks had been modified, and others had not, so replacing these blocks of cut'n'paste code was not straightforward.

If someone caught you doing this with code, they'd probably fire your ass. You could probably get away with it in documentation, especialy if you use the "self contained" line.
--
I am the very model of a K5 personality.
I intersperse obscenity with tedious banality.

[ Parent ]

Something I loathe. (3.00 / 3) (#61)
by uXs on Thu Oct 02, 2003 at 03:45:35 AM EST

Cut & Paste != Copy & Paste.

--
What our ancestors would really be thinking, if they were alive today, is: "Why is it so dark in here?" -- (Terry Pratchett, Pyramids)
[ Parent ]
Even better... (4.00 / 2) (#63)
by jsight on Thu Oct 02, 2003 at 11:29:38 AM EST

I have seen people do this in code, and they also used the "self-contained" argument. *Ack*

[ Parent ]
Don't forget the wild goose chase (4.50 / 10) (#41)
by waxmop on Wed Oct 01, 2003 at 09:15:33 AM EST

You should always refer to manual B in a section in manual A, and then B should partially explain, and then refer to C for the rest.
--
We are a monoculture of horsecock. Liar

I agree (4.50 / 5) (#48)
by clover_kicker on Wed Oct 01, 2003 at 11:57:41 AM EST

Please refer to comment #47 for a detailed discussion of this point.
--
I am the very model of a K5 personality.
I intersperse obscenity with tedious banality.

[ Parent ]
If you ever do a sketch for the SunONE server set. (2.80 / 5) (#43)
by datamodel on Wed Oct 01, 2003 at 09:27:58 AM EST

Do let me have a look... Ta.

don't forget the importance of linking... (3.87 / 8) (#46)
by senjiro on Wed Oct 01, 2003 at 11:05:11 AM EST

All good documentation should constantly and consistently hyperlink to itself, and obscure references for the words and technical jargon used in it. Ideally, prolific use of anchors to itself, hopefully 5 or 6 deep per page. This enables you to spend lots of time looking up references, doing google searches, and appearing to have a handle on modern documentation writing.


it is by will alone that i set my mind in motion
yet another 2-edged sword (4.25 / 4) (#47)
by clover_kicker on Wed Oct 01, 2003 at 11:54:45 AM EST

I agree that massive linking can obfuscate, but it also has tremendous power to organize.

The Meta Project has a great demo of fully hyperlinked *nix man pages.

That demo page shows you where the vi executable lives, where it's configuration and temp files are stored, what other programs are merely symlinks to vi, what man pages refer to vi, where the vi source code lives, and the system white papers which refer to vi. All of those are links, so you're 1 click away from the manpage for ex(1).

Here's another cool example - /etc/fstab shows you which commands/system calls use fstab, points you to the manpage, etc.

The main alternative to linking is duplicating information. As has been discussed elsewhere in the thread, this can lead to maintenance problems.

Almost any technique can result in clarity or confusion. Dogmatic use of any technique will probably result in a mess. Writing good documentation is hard.
--
I am the very model of a K5 personality.
I intersperse obscenity with tedious banality.

[ Parent ]

Fully Hyperlinked Man pages? (3.50 / 3) (#55)
by senjiro on Wed Oct 01, 2003 at 03:59:47 PM EST

Great, now I'm out of a job! If man pages were easy to read, understand and follow, and actually contain all the information they have over there, you really wouldn't need "UNIX Gurus" anymore.

Thanks for ruining my chosen career path, Meta Project.

it is by will alone that i set my mind in motion
[ Parent ]
pfft. (3.00 / 3) (#56)
by clover_kicker on Wed Oct 01, 2003 at 04:26:25 PM EST

You or I can look at those pages and use them to quickly look stuff up, or maybe learn something new.

It might as well be fully hyperlinked Swahili for someone who doesn't *already understand* Unix.
--
I am the very model of a K5 personality.
I intersperse obscenity with tedious banality.

[ Parent ]

I love it (4.40 / 15) (#51)
by epepke on Wed Oct 01, 2003 at 12:46:22 PM EST

Another idea:

Write Professionally

As every academic knows, use of the first and second persons and use of the active voice are unprofessional. Avoid them. Also, never use nickel words when a $5 word will do.

Bad:
Enter "bork" to check the disks.

Good:
Verification of disks is initiated and reified by the entry of "bork" at the command line prompt.


The truth may be out there, but lies are inside your head.--Terry Pratchett


Fear is your Friend (4.53 / 13) (#59)
by pmc on Wed Oct 01, 2003 at 07:20:57 PM EST

Obfuscation, while an important tool in its own right, can be made substantially more effective by the "unqualified qualifier".

Good
Verification of disks is initiated and reified by the entry of "bork" at the command line prompt.

Better
Verification of some aspects of the performance of disks can be assessed by the use of the command line tool "bork". This tool is not appropriate for all circumstances - in these circumstances other tools should be used. Data loss should only occur in exceptional circumstances, but prudence dictates that, if circumstances permit, a full backup is undertaken before use.

Verbosity is good, but confustion, irrelevence and fear will always win: make them fear the manual.


[ Parent ]

Never use examples, offer suggestions (4.50 / 12) (#52)
by laurad on Wed Oct 01, 2003 at 12:52:13 PM EST

You've included several examples that are not only informative but also believable and interesting to read. They're almost like real-world usage scenarios even. You've gotta just resist the temptation to ever provide examples of what to do or what not to do. That's key to writing bad documentation!

Also, never offer suggestions to the reader/user, let alone one that's a "Concrete Suggestion".

Yes, definitely, put the headings and content there so it looks like you've included plenty of examples and suggestions. But, never include any useful content. That's the key: be incomprehensible.

If you're really good, then write everything in passive voice using only ambiguous, multisyllabic, multi-word nouns and adjectives and form your verbose sentences as convolutely as possible. This practice ensures the person or persons using the ideas contained in the documentation comprehend the point the writer was trying to make in only a small number of cases and successfully implement the procedures a far lower percentage of the time, while simultaneously appearing impressive and educated to the casual manager's eye (your "shiny things" statement). This practice is sometimes referred to as self-obfuscation.

you mean: (4.00 / 3) (#67)
by stib on Fri Oct 03, 2003 at 01:08:09 AM EST

The use of passive voice and adoption of ambiguous, multisyllabic, multi-word nouns and adjectives, coupled with the formation of verbose sentences which, as far as practicable should be convoluted, is, if acheivement of Worlds Best Practice is part of the goals of the writer, recommended.

I have a boss who writes like this and he's supposed to be making training material. You thought computer nerds were bad, you aint met an occ health and safety nerd..

[ Parent ]

Examples can be your friend.. (4.00 / 3) (#74)
by Steeltoe on Sat Oct 04, 2003 at 05:47:11 PM EST

By all means provide examples! If you want lots of documentation, provide lots of examples..

If you really want to write bad documentation, there's nothing like examples as inspired by Microsoft Developer Studio. Simply, make the simplest examples you can. Never show more than one possibility of using the code, and never use optional parameters and other setups. Never code the examples in a more complex context, but do it so straightforward as you could guess it beforehand. Make the examples as useless as you can.

Nothing is so frustrating as to look at examples you could have written better yourself when trying to figure out what a function can do!

Of course, you have to couple this with bad documentation of the function too, just like in Microsoft Dev. Studio! ;-)

Explore the Art of Living

[ Parent ]

Dont forget.... (3.83 / 6) (#53)
by unstable on Wed Oct 01, 2003 at 02:23:52 PM EST

Always assume the user knows how to do something.

ie
say to get report A you need to first edit query foo with the special program that automatically updates it to the current date.

in the documents you list it as

"To recieve report A, update foo to the current date."

assume that they know about the special program that automatically updates it for you instead of pouring over the 15000 line query looking for every mention of the date. (extra credit if only one entry is relevent)



Reverend Unstable
all praise the almighty Bob
and be filled with slack

<argh> ITYM 'poring' </argh> -nt (4.00 / 3) (#57)
by czth on Wed Oct 01, 2003 at 04:57:28 PM EST



[ Parent ]
Regarding Shiny Things and Project Managers (3.50 / 4) (#54)
by cathexis on Wed Oct 01, 2003 at 03:25:19 PM EST

As far as I can tell, Project Managers operate under the simple rule of "If I can't understand it, it must be quality." Annoyingly enough, this rule also seems to apply to design docs and progress reports produced by these same Managers.

And remember... (4.00 / 4) (#58)
by puppet10 on Wed Oct 01, 2003 at 05:07:01 PM EST

Following the successful completion of the documentation in the prescribed manner all questions regarding the information contained within it can be delegated to the simple phrase: RTFM.

Plagiarism (3.85 / 7) (#62)
by harrystottle on Thu Oct 02, 2003 at 08:56:34 AM EST

surely you should at least credit the relevant internal Microsoft Documentation manual from which you obviously gleaned most of your ideas...

Mostly harmless
Outsourcing (2.33 / 3) (#64)
by lvogel on Thu Oct 02, 2003 at 06:44:01 PM EST

If you want to see bad documentation, you should take a look at some of the fine products coming out of India.

We had a guy write a BizTalk adapter, which took him at least 4 months to make up one "portable" c file, which uses the Microsoft Windows 2000 Resource kit extensively, for programs like "sleep.exe". He wrote up 20 pages of documentation for this program, documentation that only makes sense to the only other Indian guy on our development team. He also made no effort whatsoever to make any kind of setup program.

For an example of bad documentation I point to his explanation of how you are supposed to use the Registry to set up settings for the inbound part of the adapter.

As a reward for his crappy work, my company is sponsoring his visa so he can come to the U.S. and work on our team. I can hardly wait.
-- ----------------------
"When you're on the internet, nobody knows you're a dog!"

-a dog

Watch out - you and your team will be replace. (2.00 / 1) (#77)
by lukme on Sun Oct 05, 2003 at 12:41:00 PM EST

Is this guys visa a h1-b or an l1?

If it is a l1 - they are probably going to outsource your entire teams effort to his Indian company.

If it is a H1-b, he will be a team member for a long time. Since he will be working for less than half the amount you work for, your job will on the line.

At this point, this guy has impressed your upper management with his technical abilities and/or price. Remember it is not your upper management who will be oursource -- it is you. Someone up there is saying, look, we can decrease our cost of development by 90% if we outsource our development to ... . If the team want to continue working there, get to know your upper management's motivation. On the other hand, if the team feels that the work environment just sucks, quit en masse (and before, just short the company's stock if your development team is a major part of the comapany).


-----------------------------------
It's awfully hard to fly with eagles when you're a turkey.
[ Parent ]
Bloody Indians! (none / 0) (#78)
by MSBob on Sun Oct 05, 2003 at 01:12:32 PM EST

I'm sure good ole' white folk would never have written such terrible documentation.
I don't mind paying taxes, they buy me civilization.

[ Parent ]
Managers and documentation (3.50 / 4) (#65)
by phliar on Thu Oct 02, 2003 at 07:44:42 PM EST

There was this job I once had... it was a large project, and design work was mostly done and implementation had begun when I joined. I was astounded at the quality of the documentation: major design decisions and justifications, ideas that didn't work, things to look out for — all documented. Not just that: it actually was updated as things changed! This inspired me to keep a diary of my first few weeks at work, which contained things like the organisation of the source code, the build system, environment variables necessary for developers — the things that people already working on the project know but that might have been opaque to newcomers. Yes, we were proud of the system, and of the documentation.

Now we skip forward about a year, when it's time for annual reviews. One of the things that the moron manager dinged most people for was the quality of the documentation! I marched in and, in a high dudgeon, demanded to know the meaning of the outrage. The documentation was bad, he replied, because marketing and tech support couldn't figure out what the thing did. I tried to point out the difference between documentation for users and for programmers... I should have saved my breath.

There were other problems with this yahoo, of course, and most of the dev team quit soon after. The company went under a little after that.

Faster, faster, until the thrill of...

This guide.... (3.00 / 2) (#66)
by Resonant on Thu Oct 02, 2003 at 09:15:24 PM EST

Did you just take Microsoft's "How to document" documentation and copy paste? :) Interesting little article, wasted a good 10 minutes of my life...just like documentation!

"I answer, 'This is _quantitative_ religious studies.'" - glor
No offence, but... (2.00 / 5) (#68)
by p3d0 on Fri Oct 03, 2003 at 01:50:53 PM EST

How to Write a How-to Guide that Seems Witty and Helpful but is Actually Neither:

  • Write it about the opposite of what you actually want to describe. It will naturally contain lots of implicit double-negatives and sarcasm that will obscure your point. Also, having been done to death, it will not be the least bit funny.

--
Patrick Doyle
My comments do not reflect the opinions of my employer.
hahhaha (3.00 / 1) (#71)
by clover_kicker on Fri Oct 03, 2003 at 04:57:14 PM EST

Maybe it really is a document aimed at embittered people about to be layed off, and the disclaimer at the end is a CYA red herring.
--
I am the very model of a K5 personality.
I intersperse obscenity with tedious banality.

[ Parent ]
Do it the IBM way (3.33 / 3) (#69)
by Orion Blastar on Fri Oct 03, 2003 at 02:11:37 PM EST

I was told this by a college professor of mine. It takes two people, one a programmer, and the other a technical writer. The programmer documents the program and writes the manual on it. The Technical Writer attempts to read it, if the Technical Writer can understand it, it gets sent back to the Programmer to be rewritten. The Technical Writer tries to read it again, if they can understand it, it gets sent back to the Programmer. Finally when the Technical Writer cannot understand a word of it, it gets sent to be published. I was told this was how IBM did their program manuals, I suppose it could work for program documentation too. :)
*** Anonymized by intolerant editors at K5 and also IWETHEY who are biased against the mentally ill ***
Be Editorial (3.00 / 2) (#70)
by Orion Blastar on Fri Oct 03, 2003 at 02:15:07 PM EST

Not sure why, but at one place I worked at, a coworker told me I was being Editorial in my Documentation. I never really understood what it meant, but it ticked her off a great deal. Could someone please explain this to me? I do not understand what being Editorial means. Not that I did it intentionally, as I don't even know what it means.
*** Anonymized by intolerant editors at K5 and also IWETHEY who are biased against the mentally ill ***
probably (4.33 / 3) (#72)
by kubalaa on Fri Oct 03, 2003 at 07:23:43 PM EST

means you were using documentation as a vehicle for personal opinions.

[ Parent ]
I tried to stick to the facts (none / 0) (#76)
by Orion Blastar on Sun Oct 05, 2003 at 10:36:21 AM EST

and didn't want to put any opinions in the documentation. Maybe she just didn't agree with my facts?
*** Anonymized by intolerant editors at K5 and also IWETHEY who are biased against the mentally ill ***
[ Parent ]
In other words.. (3.00 / 1) (#73)
by ibsulon on Fri Oct 03, 2003 at 08:27:13 PM EST

"This is stupid" shouldn't appear in the docs.

[ Parent ]
Let's not forget (4.00 / 2) (#75)
by lazloToth on Sat Oct 04, 2003 at 08:43:14 PM EST

The 20 page template containing 2 paragraphs of information relevant to the specific program.

I worked for a place that I won't name that did this. You could put the lyrics to Wooly Bully in there, they'd be happy, but if you changed a font or formatting detail, they'd tear you a new one.

Reminds me of... (3.00 / 6) (#79)
by geoswan on Sat Oct 11, 2003 at 07:55:27 PM EST

Objectives

You wish to produce documentation that:

* will impress your management, and facilitate your remaining time in that job.
* will not substantially help your replacement(s).
* does not betray obvious signs of sabotage.

This portion of your article reminds me of Tracy Kidder's book, "The Soul of a New Machine". This book was a best-seller around 24 years ago. Kidder was a journalist who got permission to hang out with and document a project at Data General that became their answer to the VAX.

I am reminded of it not because it was a poorly written book. I thought it was a wonderfully written book -- and a large number of people must have agreed -- as it made the best-seller list.

This book spent a lot of time conveying what it was like to be a newly graduated engineer, on your first full-time job, trying to meet an impossible deadline by spending a year working 60 to 80 hours per week. It did a pretty good job at conveying the excitement of a project where you lived on a combination of caffiene, anxiety and hubris.

The really amazing thing about this book was its hidden dual nature. Both geeks and non-geeks loved it. Both geeks and non-geeks loved it for completely different reasons. Both geeks and non-geeks read the same words and had totally different emotional reactions to it.

Geeks, or former geeks read about those adrenaline fueled all-night debugging sessions, and felt a vicarious excitement, because it reminded them of their own adrenaline fueled all-night sessions.

Non-geeks read about these adrenaline fueled all-night debugging sessions petrified with a horrified fascination, like watching a car-wreck, and felt a moralistic sense of superiority. They always knew geeks were fucked up and alienated, and the book confirmed it for them. No wonder scientists have fucked up the world if they can't even eat right and go to bed at a sensible hour.

At least that was the reaction among my geek and non-geek friends and acquaintances.

And this question reminds me of it. Yes, it would be interesting to hear how to craft poisoned documentation so excellently that no-one ever doubts that it was well done.

Thanks (none / 0) (#80)
by clover_kicker on Mon Oct 13, 2003 at 06:43:36 PM EST

I think :)
--
I am the very model of a K5 personality.
I intersperse obscenity with tedious banality.

[ Parent ]
Job Security by Obscurity (none / 1) (#81)
by vinn on Wed Oct 15, 2003 at 12:20:58 AM EST

I'm starting to come to grips with the fact that my employer really doesn't care about it's employees nor is my employment guaranteed in any way. It's not in my best interest to share my knowledge with anyone. Not that it's much of a concern - no one else has ever bothered to ask for any of that knowledge.

When I first started I kept meticulous notes, all nicely tucked away on my PC. At some point we instituted a formal documentation system. We have no choice but to document some of our systems. I've chosen to include really nice PDF's all culled from vendor's websites. Thus far I'm convinced no one has looked at the docs, they only seem to care that some exist.

I still keep those detailed notes.. I just don't need to share them. I've got a few copies burned on CD's for my use. The rest sit in obscure directories and never get backed up.

Yeah, about those TPS reports, mmkay. (none / 2) (#82)
by dirvish on Fri Oct 17, 2003 at 07:29:37 PM EST

I like to use the template from my TPS Reports for my documentation.

Technical Certification Blog, Anti Spam Blog
Windows Doc (none / 1) (#83)
by Verdeboy on Sun Dec 21, 2003 at 10:28:23 PM EST

I keep hearing complaints about LINUX/UNIX documentation, but Windows documentation apparently follows these procedures to the letter. It must have been written by monkeys that had often heard Windows described, but never actually used it.
--Verde

DETECTING WINDOWS USE DOWNlOAD SLACKWARE LINUX
HOWTO: write bad documentation that looks good | 83 comments (64 topical, 19 editorial, 0 hidden)
Display: Sort:

kuro5hin.org

[XML]
All trademarks and copyrights on this page are owned by their respective companies. The Rest 2000 - Present Kuro5hin.org Inc.
See our legalese page for copyright policies. Please also read our Privacy Policy.
Kuro5hin.org is powered by Free Software, including Apache, Perl, and Linux, The Scoop Engine that runs this site is freely available, under the terms of the GPL.
Need some help? Email help@kuro5hin.org.
My heart's the long stairs.

Powered by Scoop create account | help/FAQ | mission | links | search | IRC | YOU choose the stories!