On Mon, 16 Dec 2013, Radu Gheorghe wrote:
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.
well, skipping modules that aren't rewritten for v8 is reasonable, if they
aren't v8 compatible they aren't used as much, or they are contributed and we
don't know as much about them.
But I think that we really are better off documenting each module with both
styles of configs at once. It's going to be far easier to dig up all the config
options on a given module while you are looking at it rather than having to make
two passes over the module and having to do the mental context switching to get
everything back in mind when doing the second pass.
It also has the advantage that inconsistancies between the two approaches are
more obvious.
Now, ultimately this is going to be up to the people writing the docs, but
before the new docs can replace the existing docs, I think they are going to
need to include both the old and new config languages.
David Lang
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.
