[INN] #47: INN manual

INN rra at stanford.edu
Sun Dec 14 08:40:35 UTC 2008


#47: INN manual
-------------------------+--------------------------------------------------
 Reporter:  eagle        |       Owner:  eagle
     Type:  enhancement  |      Status:  new  
 Priority:  low          |   Milestone:       
Component:  doc          |     Version:       
 Severity:  wishlist     |    Keywords:       
-------------------------+--------------------------------------------------
 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

  * 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.

-- 
Ticket URL: <http://inn-new.eyrie.org/trac/ticket/47>
INN <http://www.eyrie.org/~eagle/software/inn/>
InterNetNews


More information about the inn-bugs mailing list