Re: [ns] ns Manual : For who?

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

That's exactly my point. There is no need to include huge pieces of code
(maybe only cite the filename). In many places, there is a short
description of some of the functions and how they are related ...see for
example the section on TCP agents. However, other parts are not as
organised.

My point is that maybe it is time to slow done on the code expansion and
nail down a good comprehensie documentation of the parts that are not
dynamically changing every day. As an example, I think the description of
the class hierarchy, the scheduler, the classifier...etc. require a
lot of work. Also, inline documentation looks, in many cases, like notes
written by the person who wrote the code, to be understood only by
her/him, and nobody else. With minimal effort, more care can be taken to
make comments more meaningful.

Regards,

Hussein.

On Mon, 20 Mar 2000, Tarik Alj wrote:

> I think the "ns-manual", previously known as "Ns Notes and Documentation", 
> stands as a reference for people wishing to use ns as a tool for their research. 
> Obviously when describing the simulator used, you are not going to cite pieces 
> of code... Wouldn't it be fair to say it describes ns fundamentals (for the 
> parts that are up to date...)?
> 
> Tarik.
> 
> ps: btw, every "ns-user" is bound to become an "ns-programmer" sooner or 
> later...
> > 
> > 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.
> 
>