Re: [FT] Military Overcharging

> <laugh>
> 
> Specificaitons are amazing things.
> 
> I was tasked to document a program (that had no documentation internal
or 
external).
Originally I was to use a Milspec standard. Then a different standard,
then an 
IEEE
standard (12207), then a combination, then back to IEEE. After 6 months
they 
decided on
IEEE.
> 
> They decided that they wanted "everything specified in the
specification". 
The standard,
itself, was over 200 pages (in 3 parts). 

Been there, done that.

The trouble is, that the Mil Standards themselves are actually pretty
good, IN 
THE RIGHT HANDS. 1679 a bit primitive, 2167 was OK, 2167A a bit too
terse, 498 
WONDERFUL, IEEE 12207 too terse again.

By "terse" I mean "too generally wishy-washy with no specific guidance
on how 
to shrink the results to something reasonable".

The first thing the standards do is tell you to tailor them. Basically,
these 
standards are designed to be useful on every project, from a simple
software 
module to a World Wide Command and Control System, or for that matter,
the 
Internet. All of it.

So someone *who knows how to use these standards* will take the 200+
pages, and 
tailor them to the 2-30 documents that are relevant for the task. The
standard 
actually tells you to do this, and 498 and 2167 both gave a guidebook
even 
larger than the standard on how to decide what to remove altogether or
combine.

Basically, if you ever find yourself making a document that won't
actually help 
you make, use or maintain the system, you're using the standard wrong,
and 
should go-back and do some more tailoring.

Whereupon you will find that the clueless customer says "you're not
giving us 
what we want, we want it all! All 4000 Interface Specifications! The
Software 
User Manual for an automatic system with no manual intervention! All of
it!".

I've made systems that are completely documented according to 2167A that
had 
exactly 3 documents, each of about 20 pages, for them. 498's even
better, the 
documents are clearer and positive boons when building the system. I've
also 
seen systems documented (badly) in 1679A (predecessor to 2167A) that
were best 
measured in megapages. Literally. In one, (a great disaster) just the
data flow 
model took up 10 cubic metres of space. The savvy but unethical company
gave 
the clueless customer exactly what they asked for- nay, DEMANDED - a
totally 
useless waste of effort, at a cost of hundreds of millions.

I'd recommend to any software developer that they have a good, solid
read of 
Mil Std 498, AND the handbook. And it's absolutely vital to realise that

although you *can* write 300+ different documents for a system according
to the 
standard, that is no reason why you *should*. For example, a missile
guidance 
system that fits in the nose of an anti-air missile shouldn't have a
separate 
user's handbook, GUI design document, and system administrator's manual.
And a 
package that runs on 1 PC might best just have 3 documents - a combined 
Requirements/Design/Maintenance document, a combined Installation
Guide/User 
Manual, and a Sales Brochure/Executive Summary.

But there's always some clueless newbie that suspects that the Big Bad 
Contractor's trying to pull a fast one on them, and not giving them
enough 
documentation. So they reject the clear, concise, complete and useful
first 
draft for something that groans under its own weight, which only God
alone 
(certainly not the author) knows if it's complete or not, and which it
would 
take an army of thousands several decades to review properly. They then
spend 9 
of the 10 available days for review arguing about the exact meaning 
of "shall", "should, and "may" even though these have very specific and
well-
defined definitions in the standard.*

I've seen a fully grown Lieut Cdr of the US Navy tear pages out of
documents 
and eat them in frustration at one of these meetings. (Then he and I
adjourned 
for a few minutes, got a pen and some Corflu, went to the photocopier,
made a 
few changes while the Clue-Free Zone in the conference room gabbled on
about 
definitions, shook hands on it, so all was well in the end.)

I guess the only difference between Australia and the US is that in
Australia, 
$30 US per hour is a good rate for someone with 15+ years of experience,
not 
$300... FWIW I'm leading the software team doing the spaceflight
avionics for a 
6-payload scientific satellite, and I get less than $30 US per hour...
but I'd 
do it for less, it's fun!

* OK, here's the potted version.
Shall - means it shall be done this way.
Should - means it should be done this way, unless you find a better (or
much 
much cheaper that's almost as good) way.
May - means a suggested way, but there are probably others that are
better, and 
if you know of one, use that instead.

So the New Kil-O-Zap PDS System:
SHALL be able to successfully kill X standard targets in Y
seconds.(though X+1 
would be better!)
SHOULD use existing standard Navy components (unless KV-mart ones at
1/100 the 
price are even better, so we could refit the whole fleet)
MAY use a missile system as the kill mechanism (though a beam weapon is
fine if 
that's what's needed)

----------------------------------------------------------------
This message was sent using the AustarMetro Internet Web Mail System.
http://www.austarmetro.com.au/