Re: J4 - presentation/discussion on "Future of the COBOL Standard"

On Sun, 16 Mar 2008 12:01:28 +1300, "Pete Dashwood"
<dashwood@[EMAIL PROTECTED]
>
wrote:

>"Robert" <no@[EMAIL PROTECTED]
> wrote in message 
>news:n80nt3hh9uebhvl0g5knjnsmcdmfauj7o6@[EMAIL PROTECTED]
>I saw your post where this had happened to you over a Business
Requirement. 
>I strongly sup****t your desire for clear English.
>
>Your colleague(s) saw fit to re-write your SOR with more buzzwords and 
>jargon. This indicates that what you did was just too general or was more

>general than is normally the case on that site. Sometimes we use jargon 
>because it communicates unequivocally; sometimes it is just part of 
>protecting the mystique, in the interest of job security... :-)

Technical language can give a false illusion of accuracy. My Business
Requirement is the
fourth attempt to solve a problem. The first three were precisely written
and implemented,
but produced wrong answers because they made false assumptions about the
real world. 
One assumption was that a US wireline telephone number can be
geographically located by
taking the first six digits of the number and looking up the location of
the central
office containing the switch handling that exchange. Can you figure out
why that sometimes
gives wrong answers? Hint: old numbers are in area code 909, medium aged
ones are in 915,
newer ones are in 951. The answer is not call forwarding nor foreign
exchange.

Technical language is sometimes used to silence semi-technical subject
matter experts.
When the problem is described in language they can understand, they
embarrass us by
bringing up facts we don't know, for example legal issues. That's what
they're supposed to
do. When the spec is in technical language, they agree to everything
rather than admit
they don't understand it.

>At the end of the day, it really doesn't matter what you or your 
>colleague(s) thought about your do***ent; what matters is what the person

>who had to use it thought. A Statement of Requirements needs to
communicate 
>clearly. Using plain English is a good way to acomplish this (in fact,
using 
>plain English is a good way to communicate in most situations...), but,
if 
>(and only if) the do***ent was perceived BY THE USER as failing to 
>communicate, or leaving things unclear, then it must be amended, or (and 
>preferably, in my opinion) some face to face discussion between the
author 
>and the user needs to take place.

Face to face is impractical when parties are all over the planet. We do
in-person meetings
via NetMeeting and telephone. When nontechnical management is involved, we
add closed
circuit TV. NetMeeting has become the norm in large US companies. It is
actually MORE
effective than a conference room because everyone can SEE what you're
talking about.
You're not limited to PowerPoint slides nor are you limited to text, as in
this forum.

Take for example code review. In the old days it was done with hardcopy
listings and
colored marker pens in a conference room. Now it is done with Beyond
Compare pointed at
the code repository. Participants, who are often in different cities or
countries, are all
looking at the leader's desktop (screen). When another participant wants
to illustrate a
technical point, the leader ****fts focus to that person's desktop. 

Conducting meetings in this environment requires virtuosity with software
tools. Effective
leaders do not fumble.

>If one of my colleagues picked up a do***ent of mine and started editing
it 
>to fit his own perceptions of how such a do***ent should be written, I'd 
>probably beat him about the head and neck with it :-). (Perhaps the
implicit 
>recognition of this, is why no-one's ever done it... :-))
>
>Seriously, if someone felt the need to edit what I wrote, I'd definitely
sit 
>down and try to understand why they did.

Turn on the audit feature in Word. They can even add sticky notes to
explain the rationale
for a change. 

>The need for written requirements is a hangover from the Waterfall and is

>more about "cover your arse" and control than it is about communicating.
In 
>more dynamic and fluid environments (like Agile...) face to face 
>communication trumps it easily. If you work in an environment where you 
>EXPECT requirements to change (even during development), and actually 
>WELCOME that change, you won't be writing down requirements. (You WILL be

>writing down timeboxed, prioritised goals (agreed jointly with the
Business) 
>that will become deliverables out of the timebox...)

All too often I work on code that lacks explanation of WHY it's doing
something. Sure, I
can see WHAT it's doing, but that's not enough. I write comments to
explain non-obvious
background, sometimes whole paragraphs. On one project I put hot links in
the code, tying
it to the technical spec. The code reviewer deleted them, said they were
"unprofessional".
I also linked the technical spec to the business spec. The do***entation
reviewer deleted
those links, for the same reason.

Yeah, right. Mixed case code is still considered unprofessional in
mainframe shops. At
least everyone knows it's a dying culture.

>(I've just been writing about exactly this in the book I am fini****ng.
There 
>is much more to it than I can elucidate here.)

Beware of advocating 1990s ideas.