My comments about ditching pre-v8 stuff and old config format are about priorities. Old versions and formats should be documented eventually, but the new format and new versions should have higher prio IMO. So at least someone willing to try the latest version (who might become a contributor!) can find the needed docs.
Instead of taking one module at a time and documenting it for all the versions + the old-style format, I would start by showing what it does in 8.1.3. Some modules are not ported to v8 yet, so I'd skip them in the first phase, because they have a higher chance of becoming obsolete. Only after v8 docs are done properly I'd start adding: - old-style config stuff - info about older versions - modules that weren't ported to v8 yet Otherwise we'd have a higher risk of staying where we are: lots of info scattered all around the Internet, because documentation won't be able to catch up with features. Think about how you patch code. How do you do it? 1. fix all the bugs of the latest version first, then move on to backporting 2. do a fix, backport to all the "significant" versions, then move on to the next fix I think 1. is better for most situations, because the latest version is where effort is worth investing. And I think it should be the same with documentation. And I don't think the old format is good for anything else than backwards compatibility. Which implies familiarity with sysklogd users, etc. Valid arguments, but we shouldn't cling on to that. Take the omfile example. Using explicit omfile shows users that rsyslog is modular and that it has other options beyond the prio filter and the path. Makes you look it up if you need to. How do you search for docs if "*.* /var/log/messages" doesn't work? You don't, you complain that rsyslog sucks. I've seen people do that, and who can blame them? You'd expect people to google "why *.* doesn't work"? If a new-style config format is worse than an old one in any significant way, it's probably a bug. Either of code or of documentation. Currently, I think most such stuff is related to documentation. 2013/12/16 Rainer Gerhards <[email protected]> > On Sun, Dec 15, 2013 at 3:25 PM, Rainer Gerhards > <[email protected]>wrote: > > > Branches also make maintaining multiple versions really easy. I'll blog > > tomorrow how i do it for rsyslog. > > > > As promised, this is a description of my workflow: > > > http://blog.gerhards.net/2013/12/how-i-maintain-multiple-rsyslog-versions.html > > It's *extremely* easy to mange the multiple versions. > > In spite of this, my recommendation to the doc project is > > a) create v5-stable, v7-stable, v7-devel, (master) branches > b) import rsyslog v5-stable doc to v5-stable > c) merge v5-stable to v7-stable (git pull . v5-stable) > d) import rsyslog v7-stble doc to v7-stable; you now get a diff, commit > that one > e) merge v7-stabe to v7-devel > f) import rsyslog v7-devel doc to v7-devel; you now get a diff, commit that > one > g) now it beomces a bit tricky, checkout master, delete evertyhign, commit > (sorry....) > h) merge v7-devel into master > i) import rsyslog master doc to master; you now get a diff, commit that one > > At that point, you have the same structure that the main project has and > you can now easily make doc updates using the described workflow. It's > really worth it! > > I'd suggest to support v5-stable, even though it is outdated. Many distros > ship it (even older versions...), so enhancements to it would definitely > help improve rsyslog perception. > > Sorry again for not thinking enough in depth about it initially. As I said, > I hand't expected we get such good results so quickly ;) > > @James, please let me know how you think you'll proceed, as this affects > the way I contribute updates to the doc. > > Rainer > _______________________________________________ > 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. > _______________________________________________ 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.
