Since I know I can submit documentation updates through Github I'll be putting up some based on some of the items I've learned from trial, error and discussion on this distro.
-- James -- Sent from my mobile -- ----- Reply message ----- From: "Rainer Gerhards" <[email protected]> To: "rsyslog-users" <[email protected]> Subject: [rsyslog] Rsyslog => Apache? Date: Thu, Dec 12, 2013 2:34 PM On Thu, Dec 12, 2013 at 8:45 PM, David Lang <[email protected]> wrote: > On Thu, 12 Dec 2013, Otis Gospodnetic wrote: > > Here's an example. Radu found Rsyslog github repo. It's at >> https://github.com/rgerhards/rsyslog/ . >> >> Quick comments: >> * May be better to put under https://github.com/rsyslog/ and plan on >> treating "rsyslog" as an org *assuming* one wants to add others to this >> org >> * I could not find this with Google. What does that say? >> https://www.google.com/search?q=rsyslog+github+repo >> * There is no link to that from http://www.rsyslog.com/ >> * The README at https://github.com/rgerhards/rsyslog is kind of >> non-existent. Good Github projects make good use of having a nice README >> there and make use of the simple markup to make it readable. >> * The README at https://github.com/rgerhards/rsyslog points people back >> to >> rsyslog.com >> * The README at https://github.com/rgerhards/rsyslog points to doc dir, >> but >> ... check out index.html: >> https://github.com/rgerhards/rsyslog/blob/master/doc/index.html >> * Can somebody easily fix things now without going through Adiscon? Edit >> the README and commit? >> > > well, they can do it without going through Adiscon, but they would need to > go through Rainer. Since this is his github account, the fact that he would > need to approve the change is not surprising :-) > > > Please note note note note note: the above are not complaints. I've been >> involved in OSS too long to be like that. I'm just trying to use a >> concrete example of why the Github effort may not have been effective so >> far and a few simple and cheap examples of how things can be improved. >> > > so let's look at what we can do to make this experiment work better. > > the documentation needs to be improved, that's a weakness in rsyslog > overall, but I would rather Rainer spend his time writng code than > documentaion. > > It's not that code is more important, but it's that code requires more > knowledge of the specifics, so it's much easier to have someone new start > writing documentation than code. > > It's also that a developer is not necessarily a good documentation writer, especially if the doc is not targeted at experts. I frankly admit I am not good at writing doc, at least that kind of doc. And this is the doc most importantly needed. Believe it or not, I think that the current doc set contains almost all information and is very easy to browse ;) Why do I need to say more than "this is the RFC5424 app-name" when I want to describe that item ;) IMHO we need two roles urgently, and do so since long: a) good doc writers, especially for beginner's doc b) community managers where a community manager is someone who makes sure that rsyslog is in the press, becomes well known, etc. Big companies like Balabit (syslog-ng) can all fund this themselves. Adiscon simply can't. We are happy that rsyslog finally has begun to pay for my work and a co-worker for tech support. But that's it.The majority of the company is still funded by our Windows products. Of course, we could go the startup big money way of things. I suspect this would be of big benefit for the rsyslog community. Note that we have the rsyslog wiki, which just requires approval for account creation due to spam issues which we could not solve otherwise. There is also the forum, where a helping hand is alway welcome and does not require any involvment at all from Adiscon. On occasion, I have als offered full write access to the rsyslog site to those that seemed seriously interested in it - but nobody ever took up on that option. It's still an open offer. So there are many ways to contribute, especially to doc. On credits: it's very important to me to give proper credits. Not all is automatic, actually most patches come as non-git patch, so I manually make sure the author info is correct. As a side note, this also tells me that most folks that acutally commit seem not to care about git pull requests (or github) at all. Maybe that's just another indication a community manager would help ;) Let me phrase it this way (not meant harsh, but reality as I perceive it): It would be useful to have more people who actually *start doing* what they propose, even at the expense of less improvement proposals ;) Cool ideas really don't help the project if they boil down to "go find someone who does the work"... Again, no bashing intended, but the result many of those discussions Rainer > I've contributed a few changes to both code and documentation. > > most of the problems that you are pointing out boil down to documentation, > and usually not very complex documentation. The google results boil down to > documenation and links as well (since Google ranks pages based on this) > > So, let's talk about what changes should be done to the various pages that > you link to above to make things work better. > > > where on www.rsyslog.com<http://www.rsyslog.com> should there be links to the > github repo? I > would say that they probably belong on http://www.rsyslog.com/doc/ > build_from_repo.html > > this page is part of the rsyslog repo ( /doc/build_from_repo.html ) so > modify it and submit a pull request :) > > I'll try to get some time in the near future to make a patch that does a > better job of giving instructions on downloading and installing all the > dependancies. > > the github readme documents can probably just be replaced. You have strong > opinions on what they should say, do you want to take a stab at writing > replacements? > > > I think you are focusing too much on the ability to commit without anyone > else reviewing things. Review is good. > > The way that Linux development is able to do this is that Linus has been > working with people for a long time, and he has developed trust in the > judgement of many people, so when when these people send him a pull > request, he can just commit the changes without spending any time reviewing > them, but he may need to spend time on the merge if there are conflicts > with other work. > > Right now, rsyslog has this to a limited extent with the contributed > modules, if Rainer gets a pull request from the people who contributed a > module, he will probably not do much more than glance at it before merging > it. > > If there were more active contributers, in a codebase as small as rsyslog, > I would expect that we would end up with more people becoming experts in > specific areas and funneling contributions in their area to them then > Rainer would need to do far less reviewing of the patches arriving through > that person. > > But one thing to keep in mind, rsyslog is still a pretty small project, > there are a lot of things where changing something results in changes being > requires all over the place. The module interface changing in v8 is a prime > example of this. > > 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. > _______________________________________________ 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.
