[ns] ns Manual : For who?

["A. Abou-Zeid" <hussein@lagrange.ee.washington.edu>]

To ns CEO's,

I think the ns-manual currently is, well, to say the least, it largely
under-represents the network simulator. Reason? No intended audience.
Obviously, the ns notes and documentation is a huge overhead, which is
always the case with software documentation. But, I think the maintainers
of the ns manual need to make up their minds on who the intended audience
should be; ns users, or ns programmers. Seems the ns documentation is just
something in between, and hence, is just a mere overhead. Starts by simple
presentation, and then, boom, messy code. One can always read the
messy code from the source files, and, hopefully, the documentation should
guide the reader through the interconnections between different code
blocks (functions, procedures, or whatever you prefer to call it), not
just throw the code at the reader.

Could you imagine how many pages would remain in the ns documentation
(currently 302 pages) if the pure code blocks are eliminated?

And finally, I wonder how many users/programmers really use this document.
As a starter, my learning curve started from Marc Greis tutorial,
exploiting the tcl examples in ns distribution, stumbled on ns Manual, and
then recovered by going through the code, and searching the ns archives,
which is in many cases, the _real_ source. I still check the ns manual for
info, but, as a scale from 0 to 10 for answers found in the documentation,
the hit ratio is definitely below 3.

Finally, for fairness, one must state that some ns manual sections are
better written than others.

I hope this criticism has been constructive. Too bad there are no
contributed ns documentation as well.

Best regards,

- Hussein.
p.s. They once taught us the term/concept of "software crisis" as
undergrads. And with all the O.O. design hipe, I  keep wondering if it's
ever going to be over.