Comment On Very, Very Well Documented

Just about all of the systems I’ve written about here share quite a few things in common: they are poorly designed, poorly coded, and even more poorly documented. Today, I’m happy to share with you a system that doesn’t quite fit in with all the rest. It’s actually very sound software and, most of all, it’s well documented. Very, very well documented. [expand full text]
« PrevPage 1 | Page 2 | Page 3 | Page 4 | Page 5Next »

Re: Very, Very Well Documented

2007-03-05 13:32 • by zip
Well, unlike some stuff here, this one shouldn't have anyone refusing to believe it's real.

I wouldn't have been too surprised to see the words USA in there somewhere....

Re: Very, Very Well Documented

2007-03-05 13:35 • by AbbydonKrafts
124654 in reply to 124651
I'm stunned.. that's so insane.. it's just.. gah! The words just can't describe it. Requiring a specific "8 meters" of documentation is worse than most of the code I've seen on here. *sigh*

Re: Very, Very Well Documented

2007-03-05 13:38 • by obediah
124656 in reply to 124651
zip:
Well, unlike some stuff here, this one shouldn't have anyone refusing to believe it's real.


I don't know. A game developer that delivers on time and bug free? ;)

Re: Very, Very Well Documented

2007-03-05 13:39 • by Kerin
Oh lord. This is probably the best/worst WTF on here in some time.

I can't wait for some twit to chime in with "The REAL WTF here is..."

Re: Very, Very Well Documented

2007-03-05 13:41 • by whitey77
bureaucrats will be bureaucrats. Isn't this the norm for gov't work?

What happened to the captcha?

Re: Very, Very Well Documented

2007-03-05 13:42 • by Steve99 (unregistered)
That's not so different than at my last job. The thicker the document, the more you were praised. And then... plunk...right down onto the shelf and never opened again.

IT's A TRAP

2007-03-05 13:42 • by ZergMortron (unregistered)
THE REAL WTF here is..
they used meters. We all know ONLY COMMUNISTS USE THE METRIC SYSTEM BY CHOICE!! And communists == enemy to america.

Re: Very, Very Well Documented

2007-03-05 13:43 • by Horray (unregistered)
It's a happy ending!

captcha: howdy (ol' par'ner)

Re: Very, Very Well Documented

2007-03-05 13:43 • by evo (unregistered)
I caught a system thiiiiiiiiiiiiis big!

Re: Very, Very Well Documented

2007-03-05 13:50 • by Archon (unregistered)
"I wouldn't have been too surprised to see the words USA in there somewhere...."

Yeah, the USA part is how the country got the freedom to outsource the development needs in the first place.

Re: Very, Very Well Documented

2007-03-05 13:53 • by Carnildo
124672 in reply to 124656
obediah:
zip:
Well, unlike some stuff here, this one shouldn't have anyone refusing to believe it's real.


I don't know. A game developer that delivers on time and bug free? ;)


Since they didn't need to get it out on time for the Christmas shopping season, I find it quite believable.

Re: Very, Very Well Documented

2007-03-05 13:53 • by Rolf (unregistered)
8 meters or 8 feet? 8 meter * 3 feet = 24 FEET! Holy cow!

captcha: darwin ... make sense, dinosaurs such as that should die! :P

Re: Very, Very Well Documented

2007-03-05 13:54 • by WhatTheFaq (unregistered)
It's for this kind of situation that the phrase "this page intentionally left blank" was invented.

Re: Very, Very Well Documented

2007-03-05 13:56 • by George Jansen (unregistered)
A couple of the details seem odd. Your basic retired general mid 1990s would have had his prime flying years in during the Cold War. The Russians shot down the odd US reconaissance plane and may have for all I recall mixed it up with US planes in Korea, but "vast experience in aerial warfare"? Aerial warfare training, perhaps. And the rest of the Warsaw Pact got out and about even less.

Also the notion of illustrating 8 meters of documentation by spreading his arms. I can manage something under a two-meter stretch. I don't say he didn't offer 2 for 8, but it sounds odd.

Re: Very, Very Well Documented

2007-03-05 13:57 • by freelancer (unregistered)
124677 in reply to 124663
ZergMortron:
THE REAL WTF here is..
they used meters. We all know ONLY COMMUNISTS USE THE METRIC SYSTEM BY CHOICE!! And communists == enemy to america.

HEY! I use meters (I live in Sweden), and I am NOT a commie!

Re: Very, Very Well Documented

2007-03-05 14:04 • by snoofle
124679 in reply to 124677
Having worked for military subcontracters at the start of my career, I can see someone demanding a certain volume of documentation. We used to do it all the time. My favorite method of growing documents was to take a schematic, and break it down into a master, and sub-drawings, and then reference back and forth. This way, instead of having one easy-to-read all-on-one-page diagram, it was spread over 20+ pages of sub-assemblies, sub-sub-assemblies, etc.

And for an added bonus, we had a photo-finishing shop back then to take nice professional pictures for the manuals, and they used to put the pages on a metal table (sooo close) for photographing....

Good times.

Re: Very, Very Well Documented

2007-03-05 14:05 • by EvanED
124680 in reply to 124677
freelancer (paraphrased):
I live in Sweden and I am NOT a commie!


Does... not... compute...

(Sorry, I kid. Sweden's very nice. I had an unexpected afternoon in Stockholm last summer when my flight back to the US was canceled.)

Re: Very, Very Well Documented

2007-03-05 14:10 • by Diamonds
124682 in reply to 124675
George Jansen:
A couple of the details seem odd. Your basic retired general mid 1990s would have had his prime flying years in during the Cold War. The Russians shot down the odd US reconaissance plane and may have for all I recall mixed it up with US planes in Korea, but "vast experience in aerial warfare"? Aerial warfare training, perhaps. And the rest of the Warsaw Pact got out and about even less.

Also the notion of illustrating 8 meters of documentation by spreading his arms. I can manage something under a two-meter stretch. I don't say he didn't offer 2 for 8, but it sounds odd.


The Real WTF (TM) is this thought process:

- A retired General in 1990 would have flown during the cold war. (good so far)
- The Soviet Union had only a few air engagements with the US during the cold war. (starts to fall apart)
- Therefore, because the Soviet Union only had battles with the USA... he must have either been in Korea or training his whole carrier. (worse than failure)

A good starting for a Ex-Soviet retired general's combat experience is not going to be the USA...

Re: Very, Very Well Documented

2007-03-05 14:12 • by ewhac (unregistered)
8 metres is overkill, but 500 pages is pathetically slim.

Were the complete mechanical drawings provided for the simulator cockpit? Were the specifcations for each part of the simulator provided, and how each part that was actually used in the simulator met that specification? Was the thinking of the developers documented along each step of the way -- not just the 'how' but the 'why' of every aspect of the system, so that it could be reproduced, repaired, and/or improved by a skilled tech with no previous knowledge of the system?

I mean, this is serious sh*t, and the lives of courageous men and women depend not only on the original job having been done well, but the jobs done by everyone else who comes afterward. And they can only do that if they're made part of the original collaborative process. And, like it or not, that's done via... Documentation.

So, yeah, there's a WTF here, but it's probably not the one you think. And it may well be several years before it emerges.

Schwab

Re: Very, Very Well Documented

2007-03-05 14:16 • by Volmarias
124687 in reply to 124683
ewhac:
8 metres is overkill, but 500 pages is pathetically slim.

Were the complete mechanical drawings provided for the simulator cockpit? Were the specifcations for each part of the simulator provided, and how each part that was actually used in the simulator met that specification? Was the thinking of the developers documented along each step of the way -- not just the 'how' but the 'why' of every aspect of the system, so that it could be reproduced, repaired, and/or improved by a skilled tech with no previous knowledge of the system?

I mean, this is serious sh*t, and the lives of courageous men and women depend not only on the original job having been done well, but the jobs done by everyone else who comes afterward. And they can only do that if they're made part of the original collaborative process. And, like it or not, that's done via... Documentation.

So, yeah, there's a WTF here, but it's probably not the one you think. And it may well be several years before it emerges.

Schwab


I think they were providing the documentation for the software that ran on the flight simulator hardware. I'm willing to bet that they had no part in actually creating the hardware, putting it together, etc. Their extent of it was probably reading from /dev/joystick.

Considering that the pilots who "flew" it raved about it, I'd say they did a good job.

Re: Very, Very Well Documented

2007-03-05 14:19 • by Henry (unregistered)
124689 in reply to 124677
freelancer:
ZergMortron:
THE REAL WTF here is..
they used meters. We all know ONLY COMMUNISTS USE THE METRIC SYSTEM BY CHOICE!! And communists == enemy to america.

HEY! I use meters (I live in Sweden), and I am NOT a commie!


Sweden is very nice. I like Swedes. My granddad was born in Sweden. However we are pretty sure it has at least a pinko socialist government and media if not right out blatant commie.

http://stefanolsson.nu/2006/12/02/swedish-television-honours-castro/

Re: Very, Very Well Documented

2007-03-05 14:19 • by Lies, damn lies, I tell you... (unregistered)
Were it not for the flight simulator, this would have really sounded like Bohemia's canon fodder simulator...

Re: Very, Very Well Documented

2007-03-05 14:21 • by stratos (unregistered)
isn't this why the appedix was created?

aka

"This program is written in C, please see appendix A for the complete specifications of the C programming language. The program is written for a x386 processor, please see appendix B for the complete specifications"


Also, thinking easth europe, thinking reaslistic flight sims, i'm thinking maddog simulations

Re: Very, Very Well Documented

2007-03-05 14:21 • by themagni
124693 in reply to 124660
whitey77:
bureaucrats will be bureaucrats. Isn't this the norm for gov't work?

What happened to the captcha?


Congratulations, you are now a registered user. You will no longer see the captchas.

You can also be quoted in the forums without your name getting lost. (Unless that's fixed.)

Re: Very, Very Well Documented

2007-03-05 14:22 • by Tim (unregistered)
124694 in reply to 124654
8 meters is, what, a couple thousand bucks' worth of paper? Still probably hundreds of thousands cheaper than a no-bid contract with an established defense contractor.

Re: Very, Very Well Documented

2007-03-05 14:23 • by themagni
124695 in reply to 124674
WhatTheFaq:
It's for this kind of situation that the phrase "this page intentionally left blank" was invented.


...and 200lb test bond.

Re: Very, Very Well Documented

2007-03-05 14:27 • by Belcat (unregistered)
124696 in reply to 124663
ZergMortron:
THE REAL WTF here is..
they used meters. We all know ONLY COMMUNISTS USE THE METRIC SYSTEM BY CHOICE!! And communists == enemy to america.


Hmm, don't look now, but there's commies just north of you... In Canada we use meters more than we use feet.
I wonder if Mexico has converted to metric yet? Only the US uses such a cumbersome labour-wasting system. And GM wonders why the Japanese are making better cars.

Re: Very, Very Well Documented

2007-03-05 14:32 • by AnthonyG
Any man that can extend his arms 8 meters out is right about anything in my opinion...

Re: Very, Very Well Documented

2007-03-05 14:36 • by freelancer (unregistered)
124699 in reply to 124689
Henry:
freelancer:
ZergMortron:
THE REAL WTF here is..
they used meters. We all know ONLY COMMUNISTS USE THE METRIC SYSTEM BY CHOICE!! And communists == enemy to america.

HEY! I use meters (I live in Sweden), and I am NOT a commie!


Sweden is very nice. I like Swedes. My granddad was born in Sweden. However we are pretty sure it has at least a pinko socialist government and media if not right out blatant commie.

http://stefanolsson.nu/2006/12/02/swedish-television-honours-castro/


First of all, a country's people does not neccessarily have to agree with it's government. That's why he (Stefan Olsson) wrote that post in the first place. Second, last year our socialist government was replaced by a liberal government, so no, we don't have a socialist government. Besides, which I stated in my first point, I didn't agree with the previous government anyway (me and many others, obviously), so I actually managed to use the metric system and NOT be a commie at the same time. Go me! :D

Re: Very, Very Well Documented

2007-03-05 14:50 • by DustinMichaels
124703 in reply to 124651
These guys are dorks.

They should of just made 8 meters of documentation using the poetry creator. NO QUACK

Re: Very, Very Well Documented

2007-03-05 14:59 • by Will (unregistered)
124704 in reply to 124696
Belcat:
Only the US uses such a cumbersome labour-wasting system.


Doesn't the UK measure highway distances in miles? And beer in pints?

Re: Very, Very Well Documented

2007-03-05 15:00 • by Gedoon (unregistered)
124705 in reply to 124663
ZergMortron:
THE REAL WTF here is..
they used meters. We all know ONLY COMMUNISTS USE THE METRIC SYSTEM BY CHOICE!! And communists == enemy to america.


FYI the rest of the fucking world uses metric system! It's just the stupid rednecks called the US of A who refuse to convert.

One Royale with Cheese, please, with six kilometers of mayonnaise.

Re: Very, Very Well Documented

2007-03-05 15:00 • by eloj (unregistered)
500 pages of serious documentation, meet "order-N markov chain generator". Just start large and ramp the N down to 0 as you approach the required number of pages, and it'll fade nicely out into random gibberish.

Re: Very, Very Well Documented

2007-03-05 15:02 • by ammoQ
124707 in reply to 124692
stratos:
isn't this why the appedix was created?

aka

"This program is written in C, please see appendix A for the complete specifications of the C programming language. The program is written for a x386 processor, please see appendix B for the complete specifications"

Maybe not with intention, but this is actually a good point. Fighter airplanes are in use for many decades, so in (say) 25 years, it might be quite difficult to find the specification of the version of C that has been used for the project.

Re: Very, Very Well Documented

2007-03-05 15:03 • by BitTwiddler (unregistered)
124708 in reply to 124699
freelancer:

First of all, a country's people does not neccessarily have to agree with it's government. That's why he (Stefan Olsson) wrote that post in the first place. Second, last year our socialist government was replaced by a liberal government, so no, we don't have a socialist government. Besides, which I stated in my first point, I didn't agree with the previous government anyway (me and many others, obviously), so I actually managed to use the metric system and NOT be a commie at the same time. Go me! :D

I didn't know there was a difference ;-)

Re: Very, Very Well Documented

2007-03-05 15:10 • by Onaka The Kaka (unregistered)
:-) It's a good story even if it ain't true :-)

Re: Very, Very Well Documented

2007-03-05 15:13 • by PS (unregistered)
124713 in reply to 124663
They use the metric system in Europe too. And not all of Europe is communist. There is um, it's on the tip of my tongue, oh no, that's not in Europe, give me one more second, this is tougher than I thought, oh yes, the US consulate in any European country is not communist but they probably don't use the metric system at the consulate so disregard my first statement.

Re: Very, Very Well Documented

2007-03-05 15:14 • by ssprencel
Well, with that kind of requirement, you could fill 7.5 meters with "This page intentionally left blank.", a few vacation photos, the actual documentation and the cardboard boxes. No sweat.

Re: Very, Very Well Documented

2007-03-05 15:17 • by jkupski (unregistered)
124717 in reply to 124675
George Jansen:
A couple of the details seem odd. Your basic retired general mid 1990s would have had his prime flying years in during the Cold War. The Russians shot down the odd US reconaissance plane and may have for all I recall mixed it up with US planes in Korea, but "vast experience in aerial warfare"? Aerial warfare training, perhaps.


He could have been a "volunteer" flying for North Korea in the Korean war, or North Vietnam in the Vietnam conflict. Or he could have been a "technical advisor" to one of the many arab states to attack Israel during the cold war. Or he could have been assigned to train the Iraqi air force during the Iran-Iraq war. Or he could have been an air-to-mud driver dropping bombs in Afghanistan. Or... well, you get the point.

And that doesn't even look at what the various forces of NATO and the Warsaw Pact did during the cold war. You can call it "training" when there's an aircraft belonging to the other side six inches off your wing tip, or a 688 and an Alfa were playing hide and go seek in the north atlantic... but the crews on both sides sure as hell didn't think of it that way. It's called the cold WAR for a reason.

Re: Very, Very Well Documented

2007-03-05 15:20 • by Henry (unregistered)
124719 in reply to 124699
Well, OK. Anyway we know the metric system wasn't invented by commies, but rather the Godless atheistic wine drinking cheese eating French who are still pissed that the prime meridian goes through Greenwich rather than Paris.

http://en.wikipedia.org/wiki/Paris_Meridian

Useful Metric Unit Conversions

1 trillion microphones = 1 megaphone
2000 mockingbirds = two kilomockingbirds
10 cards = 1 decacards
1 millionth of a fish = 1 microfiche
453.6 graham crackers = 1 pound cake
1 trillion pins = 1 terrapin
10 rations = 1 decoration
100 rations = 1 C-ration
10 millipedes = 1 centipede
3 1/3 tridents = 1 decadent
2 monograms = 1 diagram
8 nickels = 2 paradigms
2 wharves = 1 paradox

After all this who could take the metric system seriously anyway.

Now if you are talking about decimal systems of measure, well the US was there before the metric system - Thomas Jefferson was the first US Secretary of the Treasury and quite sensibly set up the US with a decimal based system of currency. He probably gave the French the idea for the a decimal system during his time as ambassador to France anyway.

Captcha: muhahahaha

Re: Very, Very Well Documented

2007-03-05 15:20 • by EvanED
124720 in reply to 124706
eloj:
500 pages of serious documentation, meet "order-N markov chain generator". Just start large and ramp the N down to 0 as you approach the required number of pages, and it'll fade nicely out into random gibberish.


My math teacher when I was in 9th grade told me a perhaps-apocryphal story of one of his classmates in college. They were in a class where the instructor didn't really grade fairly, and put a lot of weight into how well he liked you. Said classmate was one of the instructor's "good" students, so always got good grades. The essay final for the class ran around, and he started writing. He wrote a page and a half of the essay, then wrote out the entire lyrics of the Star Spangled Banner, then completed the essay.

No comments on the graded work.

Re: Very, Very Well Documented

2007-03-05 15:22 • by TravisO (unregistered)
While not as excessive, I worked at a shop and each app's documentation binder had the entire source code and SQL tables printed up.

Why, I have no idea, I mean if the app god lost, why would you retype the entire app, that's what backups are for.

Leave it to say when the office was being prep'd to remodel (it had a strong 1970s motif) the printed code found it's way to the recycling bin, which freed up about five 12 foot wide shelves for better use.

Re: Very, Very Well Documented

2007-03-05 15:26 • by bstorer
For all my fellow Americans

8 meters =
314.96063 inches, or
26.2467192 feet, or
8.74890639 yards, or
0.0397677563 furlongs, or
0.00497096954 miles, or
1.59071025 rods, or
4.37445319 fathoms, or
0.00143988481 leagues, or
78.7401575 hands

Hope that clears things up.

Re: Very, Very Well Documented

2007-03-05 15:27 • by Saladin
124724 in reply to 124677
The arbitrary documentation requirement notwithstanding, I could almost actually understand the General's desire for such extensive documentation if I thought that the documentation would ever actually get looked at. And I get the feeling from this story that no living soul will ever actually crack the covers on those binders.

I say that the developers should've just put reams of blank paper into some binders and handed them over.

freelancer:
HEY! I use meters (I live in Sweden), and I bork bork bork bork bork *slaps a rubber chicken against a table*

I see.

Re: Very, Very Well Documented

2007-03-05 15:29 • by PatsFan (unregistered)
124725 in reply to 124720
EvanED:
They were in a class where the instructor didn't really grade fairly, and put a lot of weight into how well he liked you. Said classmate was one of the instructor's "good" students, so always got good grades. The essay final for the class ran around, and he started writing. He wrote a page and a half of the essay, then wrote out the entire lyrics of the Star Spangled Banner, then completed the essay.

No comments on the graded work.


As one of the "good" students, I got away with that in a high-school social studies class.

Re: Very, Very Well Documented

2007-03-05 15:34 • by akatherder
Calling European countries all communist is like saying the USA is socialist.

Re: Very, Very Well Documented

2007-03-05 15:34 • by freelancer (unregistered)
124728 in reply to 124708
BitTwiddler:
freelancer:

First of all, a country's people does not neccessarily have to agree with it's government. That's why he (Stefan Olsson) wrote that post in the first place. Second, last year our socialist government was replaced by a liberal government, so no, we don't have a socialist government. Besides, which I stated in my first point, I didn't agree with the previous government anyway (me and many others, obviously), so I actually managed to use the metric system and NOT be a commie at the same time. Go me! :D

I didn't know there was a difference ;-)

Well, at least here in Sweden, they're quite the opposite of each other. If socialists are Nod then liberals are GDI (sorry, I just played the C&C3 demo :P )

Re: Very, Very Well Documented

2007-03-05 15:37 • by ceegh (unregistered)
124729 in reply to 124696
Belcat:

Hmm, don't look now, but there's commies just north of you... In Canada we use meters more than we use feet.


And don't think that doesn't give us the willies every once in a while. Good thing they're overly concerned with maple syrup, moose, and loons to be much of a threat. (Yes, satire.)

Re: Very, Very Well Documented

2007-03-05 15:37 • by webhamster
124730 in reply to 124696
Belcat:
Hmm, don't look now, but there's commies just north of you... In Canada we use meters more than we use feet.


I actually find myself using "feet" more than meters these days mostly because of all the time I spent with my dad while renovating my house. He still refuses to acknowledge the metric system any more than he has to. Whenever I wanted to needle him a little after he gave me a measurement (in feet) for something I'd say "I went to school in the Trudeau era. Can you give me that in real measurements?"

"The metric system is the tool of the devil! Why my car gets four rods to the hog's head and that's the way I like it!" -- Abe Simpson.

Re: Very, Very Well Documented

2007-03-05 15:38 • by Will (unregistered)
124731 in reply to 124705
Gedoon:

FYI the rest of the fucking world uses metric system! It's just the stupid rednecks called the US of A who refuse to convert.


Doesn't the UK measure highway distances in miles? And beer in pints?
« PrevPage 1 | Page 2 | Page 3 | Page 4 | Page 5Next »

Add Comment