Opened 15 years ago
Last modified 15 years ago
#47 new enhancement
INN manual
Reported by: | eagle | Owned by: | eagle |
---|---|---|---|
Priority: | low | Milestone: | |
Component: | doc | Version: | |
Severity: | wishlist | Keywords: | |
Cc: |
Description
A full-blown manual for INN would be great. Here is some discussion from an e-mail message that I sent in 1999.
We currently already have what's essentially a reference manual; that's the collection of all of the man pages plus the three README.*_hook files. They need some glue, and more extensive cross-referencing, but that's not too hard.
We have the beginnings of an introductory guide, in the form of README (after the work I did about a month ago) and INSTALL, plus pieces of Elena's document. What that mainly needs at the moment is an overview of how INN works, including descriptions of the major files involved, stuck in-between those two documents and some documentation of the periodic maintenance tasks that one has to do stuck after INSTALL.
We need more general discussion of how specific parts of news work and how to do specific things; we currently have a doc on control messages but that's about it. I have a few things planned here. Part of what should go in this part is schemes for setting up specific types of servers. (If I want a basic feed and reader machine, what do I do? If I want a split feed and reader setup, what do I do? If I want to share the same reader spool across a bunch of machines, what do I do? If I want to set up a standalone server for a particular hierarchy, what do I do? How do I run nnrpd standalone rather than from innd?) Elena's document has some of that.
We're badly missing internals documentation, apart from a few really outdated library man pages.
The overall structure I'd like to see is something like this:
- Introduction
- Basic Usenet Concepts
- User's Manual
- Building and Installing INN
- Configuring INN
- Maintaining INN
- Platform-Specific Issues
- Configuration Manual
- Specific Setups
- Mixed Feed and Reader
- Separate Feed and Reader
- INN as Feed Machine
- Other Server as Feed Machine
- Farm of Readers With Same Spool
- Standalone Public Server
- Performance Issues
- Major Bottlenecks
- Choosing a Disk Layout
- Tuning an INN Server
- Filter Configuration
- Namespace Management
- Control Message Processing
- Using actsync
- Specific Setups
- Reference Manual
- Primary INN Programs
- Configuration Files
- Maintenance and Recovery Programs
- File Formats
- Library Interfaces
- Special Issues
- RFC Compliance
- Theory and Practice of Control Messages
- Programmer's Manual
- Code Structure
- Major Data Structures
- Documentation Maintenance
Anyway, that's entirely off the top of my head just now, but if you look that over, we actually have a surprising amount of that already. Particularly if you count the stuff that was in the old FAQ. It just isn't well-organized, tied together, explained, cross-referenced, and indexed.
Getting documentation, any documentation, is more important right now than any particular structure, but I'd strongly encourage people to think in terms of a structure like the above and have at least a tentative idea of where the documentation that they're writing would fit in. That way, it will be much easier for us down the road to produce a coherent and readable overall set of documentation.