[rsyslog-notify] Forum Thread: Please refactor your documentation - (Mode 'post')

[noreply at adiscon.com]

User: aaronc 
Forumlink: http://kb.monitorware.com/viewtopic.php?p=24394#p24394

Message: 
----------
rsyslog is a great piece of software and I like its features a lot. I've
had a lot of trouble understanding and using those features, however,
because the documentation is so poor. Code needs to be refactored from time
to time and so does documentation. [i:1tco0zh8]Good documentation is just
as import as any feature of your software[/i:1tco0zh8]. Poor documentation
makes it hard for administrators to do their work. Please consider a major
refactoring of your documentation. 

Some basic problems:
 - The documentation start page <!-- m --><a class="postlink"
href="http://www.rsyslog.com/doc/">http://www.rsyslog.com/doc/</a><!-- m
--> isn't a true table of contents it's only a collection of random links.
At least fix this.
 - There are too few examples (mmnormalize really needs a lot more). 
 - There are too few detailed howtos. Good documentation should be focused
on tasks.
 - The examples mix the old and new syntax in a confusing way. How about a
full default configuration that uses only the new syntax?
 
 As an example, nxlog has pretty good documentation and their format might
be worth copying.