Re: Do you have a Knowledge Officer?

On Thu, 04 Oct 2007 13:10:49 -0700, Alistair <alistair@xxxxxxxxxxxxxxxxxxxxx> wrote:

On 3 Oct, 03:36, Robert <n...@xxxxxx> wrote:
On Tue, 02 Oct 2007 12:52:08 -0700, Alistair <alist...@xxxxxxxxxxxxxxxxxxxxx> wrote:
On 29 Sep, 21:39, Robert <n...@xxxxxx> wrote:
Documentation is not maintained; all too often, updates are
completed with no time allotted to update documentation. So knowledge
is not important.

Wrong. Every line of code can be traced back through a Detailed Design and High Level
Design to a Business Requirement. And it can be traced forward through as many levels of
test results all the way to a User Acceptance Test.

I hope that was said with your tongue in your cheek. I can assure you
that many systems that I have worked in did not maintain documentation
after release and, therefore, the only reliable documentation was the
code.

You want documentation to be a single document,

Spot on. Yes. Absolutely. Too true.

There should be at least five documents or, ideally, an outliner that allows hiding and
revealing lower levels. The levels are: business plan, business requirement, high level
design, detailed design and source code. There should also be links to execution logs,
incident reports and usage statistics.

The document you have in mind is detailed design, which is fine for techies but useless to
management.


In big (F-100)
companies, they DO have a mechanism to assure it is completed for each change.

Perhaps we should have a universal standard throughout all IT
organisations for documentation standards particularly dealing with
maintainance/support requests.

There is a de facto standard. It goes by various names such as ISO-9000, CMM and SDLC; in
practice, they're pretty much the same.

Unfortunately, I have only worked in
the real world and have only been exposed to documentation that is
either non-existant, omits by default or merely lies.

It's not the real world where big companies live; it's the world of undisciplined IT
shops.

I recommend you visit a big company and ask to see the documentation framework for a
typical project, start to finish. It's very different from the world where your company
lives.

The goal is
not a reference for future changes, it is a checklist to avoid errors and omissions in the
current change cycle.

The goal is for documentation that reflects the status/structure of
the system ACCURATELY. (with or without two Rs).

Evidence of accuracy is minutes of meetings that examined it line by line, repeated until
all parties agree (typically 3-5 iterations), signed by all involved. At my current
employer, every line of documentation and code is inspected by about ten people. It
doesn't take as long as you'd think. No objections or questions are dismissed or ignored.
We do it electronically, using voice phone and Netmeeting displaying the leader's
desktop. Participants are all over the world.

We have more than a thousand development projects going. Could your company's methodology
handle more than ten?

THEY wrote the code. Don't they talk to each other?

IT people are world renowned for their inability to communicate in
clear to any but techies.

That's the stereotype; it doesn't agree with my experience.

It does with mine.

An estimated 10% of the people
I've worked with were geeks. Generally, they're not as good as they see themselves. The
very best programmers seem normal, not geeky. The only hint is rapid speech, finishing
your sentences for you, and doing things on the computer ten times faster than normal.

You have worked with some people who, clearly, are in need of
psychiatric help.

You've seen celebrities such as Torvalds, Andreessen, Cowlishaw, Montulli, Cutler, etc. Do
they seem psychotics or personality defectives?

The fastest way to evaluate programmers is to glance at a page of their code. Any code.

That is subjective.

It's much more accurate than talking to them.

I once worked for a company that had 20 world-class programmers. I went around asking
who's the best, expecting each to name himself. Surprisingly, they all pointed to the same
quiet high school student who worked there part time, looked like a Boy Scout and was a
devout Mormon. I said that's impossible. They said look at his code. I did. They were
right. A few seconds of code inspection told me more than months of conversation.

.

Relevant Pages

  • Re: Interview preparation
    ... assurance quality standards, yet are designed and proven to improve ... In the worst case writing documentation becomes goal deferment. ... The Planner thinks about what he.s doing so much, ... Strengths They do design. ...
    (comp.arch.embedded)
  • Re: hardware board design - beginner... pls help
    ... I am an electronics graduate and I wish to learn hardware board design. ... Here's a typical very simple design flow and note that each and every stage requires thorough documentation: ... There's a lot more - power requirements, battery operation?, chargers, size, weight - there's a thousand and one things that have to be thoroughly _defined_. ... Hand route any critical signals - autorouters, in general, suck for critical signals, and it's best to route the ...
    (sci.electronics.design)
  • Re: [SPARK] Code safety and information hiding
    ... around thousands of undocumented global variables. ... the documentation:). ... You want the code to enforce the design rules. ... During runs of many unit tests together, ...
    (comp.lang.ada)
  • Re: TDD: Test-Driven Design or Test-Driven Development?
    ... >>say on one hand that it is important to document the design. ... > ancillary documentation. ... Analysts are NOT software development professionals!!!! ...
    (comp.object)
  • Re: Comments in SQL?
    ... you should have actual DOCUMENTATION that lays out the table design ... design errors, which there will also undoubtably be, and also to promote ... sort through or understand all of the tables of the website. ... The database aspects are ...
    (alt.php)