From: Howard C. Berkowitz (hcb@gettcomm.com)
Date: Sat Feb 12 2005 - 03:22:16 GMT-3
At 9:52 AM -0500 2/11/05, ccie2be wrote:
>Roger,
>
>That's my point exactly.
>
>I can list one example after another where the Doc-cd is insufficient in
>providing a complete explanation.
Sometimes, I wonder if Cisco's desire to do things by process, rather
than individuals, causes this. I remember a certain routing protocol
feature where I was involved in the IETF work defining it and got to
see the internal Cisco specification for it. I know the implementer,
and, from IETF experience, he's a good, clear writer.
Then, the documentation came out on the feature. It was only about
two paragraphs, not really long enough to explain it. In any event, I
looked at them. They were all English words. Regarded as parts of
speech, you could form them into grammatical sentences. Did they make
any sense? No.
I dropped an email to the developer and asked him to read the
documentation -- which he had NOT seen prior to publication. He
agreed that given the documentation, he couldn't implement it,
either. Apparently, he yelled loudly enough internally that they let
him fix it.
It really is true that some engineers are terrible writers.
Nevertheless, there's sometimes a documentation and education fiefdom
that won't let the ones that can write do so. Sometimes, there's an
argument that such engineers are wasting their time on documentation,
but I've always found if I can't write clearly what my code is
supposed to do, it won't be good code.
In fairness, there are topics that are much more complex, in indirect
effects, than can be covered in vendor documentation. This is
especially true in BGP, as effective BGP configuration for Internet
connectivity requires understanding of a great many Internet
operational procedures that aren't a vendor responsibility.
This archive was generated by hypermail 2.1.4 : Thu Mar 03 2005 - 08:51:20 GMT-3