Documentation Wishlist
Gather all wishlist items for specific documentation on this page. If there's something you feel you can write or at least partially write, please help out and write what you can. Append things to the list below.
Perhaps each command in the TCL API should list whether the command is currently implemented in Tcl or C.
2004jun28 Dossy: Easy enough -- of course this would be "fragile" information as from one version of AOLserver to the next, it's conceivable that Tcl procs could be rewritten in C. Is it worth the hassle of keeping this attribute up to date?
Perhaps each command in the TCL API should list what source file the command is in, this could be a link to the file in the CVS repository. (for HEAD?)
2004jun28 Dossy: This makes sense for Tcl commands, but what about commands implemented in C but exposed via a Tcl command? Still point to the C source for the command?
Also, it would be nice if commands that are not in nsd.lib pointed to the module that they are in, even if that module is considered "part of the core" e.g. nsdb.
2004jun28 Dossy: I thought about introducing a "Category Module nsdb" category ... would that be good enough?
The documentation effort might go faster if we import the commands from the existing sources, such as http://aolserver.com/40drafts/tclapi/ Each command could have a link to a category page such as [Unverified], [Verified via Testing], [Verified via Source Code] that would indicate a confidence level in the documentation. Commands without existing documentation would all start out verified, and we could work on cleaning up older commands as time permitted.
2004jun28 Dossy: Considering how far along we are now (~62% done as of this writing) it probably doesn't make sense to this. To be honest, when writing the new doc page for some commands, I often refer to the 40drafts/tclapi/ docs to get ideas as to how to write the new page. But, I still try to write the new page as cleanly as possible, not just cutting and pasting the old copy text in.
A timeline of how commands were added and removed by AOLserver version might be useful, important differences between versions could just be noted in the Notes section of each page.
2004jun28 Dossy: Oh, this would indeed be awesome but I just don't have the personal bandwidth to do this kind of deep archaeology of all the API commands. I think moving forward as we introduce new commands, to note "new in version X.Y.Z" should be a must!
After the TCL API is updated, useful things to focus on might be: Module Documentation, additional usages guides for commands like nsv_*, and then overall howto, beginner guides, migration guides, etc. The best way of documenting the C API might be to move the documentation into the source files themselves and extract via one of the numerous tools that have the ability.
2004jun28 Dossy: I've examined Doxygen, DOC++, AutoDoc, JavaDoc ... none produce output that I'm happy with. What auto-documentation generators have people personally worked with that they'd recommend (names and URLs, please!)?
Eric Lee wrote to the mailing list:
Documentation in addition to the (essential) Tcl API docs:
1. Database connection. This is what brought me to AOLserver in the first place. It is the lifeline of my applications. Availability of the necessary information to connect using new releases has been tenuous sometimes and this is a worry. There should at minimum be a sample nsd.tcl with illustrations of how to connect to different DBMS's under various OS's, and current driver installation and use docs.
2. Encoding. The mystery of funny characters. There have been some very good posts on the list about this but needs to be more central.
3. ADP. I came to AOLserver from a Perl/CGI background. The transition to Tcl was obvious but I've never really gotten on the ADP bandwagon and am pretty sure there is an approach there I should have in my toolkit. I'd like to read a Thinking in ADP.
4. C and CVS. I'm not a C programmer and wouldn't call myself a software engineer. My academic background is library science, not computer science. I develop applications more than tools. With AOLserver being Open Source now there is access to fundamental information about the system. I'd like to be able to tap into this even though I can't really participate at that level but I need an Introduction to the Source Forge Environment. I've learned how to read C programs to a certain extent and have often imagined a Bluffers Guide to C to help people who want or need to get some understanding at that level.
