On Thu, May 15, 2014 at 2:43 PM, Rainer Gerhards <[email protected]>wrote:
> On Thu, May 15, 2014 at 2:11 PM, Thomas D. <[email protected]> wrote: > >> You all do your best to get these things fixed, but personally I think >> you cannot win. It is too much you need to fix. >> >> If we would start over, start with defining how we want to display >> information (to prevent things shown in 1.1; find a way how we want to >> show current and legacy syntax; how we want to structure) rewriting >> should be more easier than fixing these things today. >> ...and we should focus on the *new* syntax. The new syntax should be >> completely documented (currently, sometimes I have to read the source >> code to get some parameters or default values). Legacy syntax isn't that >> important and remember, the old documentation is still there. >> > > That was my initial approach, but a lot of folks said we need to look at > v5, too. Comment on the rewrite below, for now let's assume a gradual > update. With a gradual update, I need to work from v5 up, otherwise fixes > in older branches will result in merge hell. So my plan is/was to start > there and move up. > > >> >> The important thing is: Keep the new documentation clean. Only rewritten >> documentation in our new "format" is allowed to get added. >> >> Maybe it will take a year or more to get where we are in the moment (in >> extent of documentation), but if we would start with the most >> important/common used parts, the new documentation will be better in 2-3 >> month than the old one ever was. >> >> Thoughts? >> >> > I like the rewrite idea, but experience tells it has a major stumbling > stone: nobody want's to do this work ;) I cannot do, because I have not > enough ideas of how I could actually *do* that work. So someone else would > need to invest a serious amount of time. I had hoped that this would happen > when we started with rsyslog-doc in december, but looking at it's state in > May, this for sure did not materialize. So I again went into doc mode and > am now trying the best I can do to get us to some better (not good, not > even decent) stage. > > I just realized that this sounds a bit harsh and not as intended. I am pretty happy with the work that was done so far. Especially the migration to rst done by James, which is now a big aid in maintaining the doc better. I also think there are lots of folks who would "like" to do the work but have no opportunity. Writing the doc is *serious work*, and for it to be good you need to have tech writer skills (that I am obviously lacking). So rewriting everything from scratch is not something that you can do on a rainy Sunday afternoon. It probably requires many weeks of working on it. I guess many people underestimate this and realize soon when they begin to actually write up something. So I guess most folks simply have no time to do this kind of work, and (as usual) no company wants to fund it. I would be glad if the situation were different. Believe me, I much prefer to code, and I am much better and faster at it than at writing doc. Still, I am now taking quite a bit from my time for the doc, as we concluded earlier this year new features do not really help, better doc does. Again, I am happy to be proven wrong. If someone, or a team, comes up and rewrites the doc, I am all ears for it and will support this effort as good as I can. Most importantly, I'll make sure everything is promptly merged. Note that there *are* already people who have commit access to the repo, as well as write access to the web site. It's just that they, too, were running out of time. So the root problem is not that we (Adiscon) block anybody, the root problem is that nobody has sufficient interest and resources to work on this (think of it along the lines of the openssl security audit problem ;)). This is the long form of what I meant with "nobody wants to do this work" ;). Rainer > Besides this time issue, the current doc is merely a reference section. So > I think it would still make sense to migrate over parts of the content. But > again, as long as nobody is really serious in doing all this sorts of > things, we don't need to discuss the details I am now digging in ;) > > Again, I like the idea, but I say "it does not work". Prove me wrong, Pull > Requests are happily accepted ;) > > Rainer > > >> -Thomas >> >> _______________________________________________ >> 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.
