And I also understand how you can feel that way about v5. So let me put it another way:
As a user, if I had trouble with some piece of software, I'd be pretty much fine going to the software's site and find out that I'm using a poorly documented, 5-year-old version of that software. *Assuming* that I can easily install the latest version and that I have good documentation for it. By contrast, I'd be pretty disappointed to find partially documented stuff across all versions. Of course, the ideal case is to find good documentation for all versions. I'm very much for that, I'm just saying that we should concentrate on the latest first. 2013/12/16 Boylan, James <[email protected]> > Radu - > > While I understand how you could feel that way, you have to remember the > v5-stable release is still the one most commonly packaged in most of the > distros out there. You can't just say, 'we'll get to that documentation > later' when that is likely to be people's first exposure to the application. > > -- James > -- Sent from my mobile -- > > ----- Reply message ----- > From: "Radu Gheorghe" <[email protected]> > To: "rsyslog-users" <[email protected]> > Subject: [rsyslog] [doc] versioning > Date: Mon, Dec 16, 2013 9:11 AM > > 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. > _______________________________________________ > 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.
