On Fri, 27 Sep 2013, Rainer Gerhards wrote:
On Fri, Sep 27, 2013 at 9:16 AM, David Lang <[email protected]> wrote:
Unfortunately, nobody wants to sponsor doc development nor contribute to
it. So with limited time, it's falling behind. I try as good as I can, but
my time is currently constrained and I am obviously not the best person to
write that part of the doc (at least, I assume way too much ;)).
yes, documentation is an ongoing problem.
In the case of rsyslog, the conversion to the new syntax has actually
ended up with the documentation getting worse, not because the information
isn't around, but because the details aren't linked in to the root, too
many things are independant documents or blog entries :-(
I made an experiment and created a light version of "call" statement doc,
linking it at least to some relevant places:
http://www.rsyslog.com/doc/rainerscript_call.html
this is linked to from
http://www.rsyslog.com/doc/rsyslog_conf_basic_structure.html but the back link
takes you to http://www.rsyslog.com/doc/rsyslog_conf_global.html
I think that one thing that would be really good is the equivalent of that last
page that lists every possible v7 parameter with just a link to the page that
describes it (if it could have a short description like the old conf_global page
does, so much the better, but even without any explination it would help)
also, grammer/debian.new has several things in it that are just wrong
first off is there really a global() command? if so, is there a documentation
page for it?
then it lists action.retrycount which apparently does not exist (at least, I
couldn't find anything in hunting through the logs
I think we can all agree it's not really great. Unfortunately, it still
took me around 20 minutes (maybe even some more), what means my assumption
is right on how much effort redoing the doc is :-(
HOWEVER, I have on my whish list a kind of master index (maybe better
"master toc"), that looks like an ordered toc and will just link to the
various pieces of doc that are already available. I think that would
probably help with your observation.
Yes, that would help a lot. Even if it's not fully filled in, having a framework
that others can contribute to would help.
David Lang
_______________________________________________
rsyslog mailing list
http://lists.adiscon.net/mailman/listinfo/rsyslog
http://www.rsyslog.com/professional-services/
What's up with rsyslog? Follow https://twitter.com/rgerhards
NOTE WELL: This is a PUBLIC mailing list, posts are ARCHIVED by a myriad of
sites beyond our control. PLEASE UNSUBSCRIBE and DO NOT POST if you DON'T LIKE
THAT.
