From: Balaji Siva (bsivasub@gmail.com)
Date: Sat Feb 12 2005 - 03:30:50 GMT-3
I strongly believe that people should provide feedback to cisco
documenation folks via the option available. By providing
constructive feedback by the people who use it, it could only become
better. Changing specific documentation based on feedback is not such
a "difficult" task from what I know from cisco. So, let us all give
feedback via appropriate channel to fix it. Just making general
statements that documentation sucks or not adequate is not enough to
fix the problem as you can imagine doc-CD is a huge undertaking and it
has evolved over many years.
my 2c
Balaji
On Sat, 12 Feb 2005 01:22:16 -0500, Howard C. Berkowitz
<hcb@gettcomm.com> wrote:
> 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.
>
> _______________________________________________________________________
> Subscription information may be found at:
> http://www.groupstudy.com/list/CCIELab.html
This archive was generated by hypermail 2.1.4 : Thu Mar 03 2005 - 08:51:20 GMT-3