Hi Jerome, In short, +1 :)
IMO documentation is the area where rsyslog needs the most improvement. I would even go as far as assuming that it's one of the main reasons why v7 isn't as widely adopted as it would deserve. And the major problems I see with the current documentation are (listed in order of importance IMO): 1. There's no obvious hierarchy and organization to it, so it's hard to follow 2. Some of the documentation is outdated (eg: doesn't include the new, v7 config format) 3. Documentation is split in multiple places: what's in the package and what's in Wiki. And if you would expect the "reference material" to be in the package, while "story-like" docs would live in Wiki, that's not true. Here's a "story" in the package: http://www.rsyslog.com/doc/queues.html The thing I like most about the solution you're suggesting is that the hierarchy will be shown on the left side. To make the transition really helpful, I think someone has to spend some time to make a good hierarchy, and at least to mark the entries which need more information (eg: v7 syntax) and those which are deprecated. I'd gladly do it, but I'm extremely busy at the moment. The other thing is that, obviously, the Adiscon guys will have to accept your suggestion for using Sphinx, and also the hierarchy of whoever spends time on making it. Best regards, Radu 2013/5/10 Jerome Renard <[email protected]> > Hello, > > A couple of days ago, Rainer ask me to update the doc to include the > new configuration flags I added for omelasticsearch. > But then I realized I had to update a raw HTML file and I was > wondering if there was a simpler way to contribute to the > documentation. > > So I made an experiment with Sphinx [1] and converted a couple of > existing documentation pages to ReST which is the format Sphinx > supports. > Doing the conversion was quite easy, especially with the help of PanDoc > [2]. > > You can have a look at what some documentation files look like with > ReST in Sphinx here: > - https://github.com/jeromer/rsyslog-alternativedoc > > If you want to build the documentation, just install Sphinx and run make > html. > If you are lazy you can still have a look at the attached tarball [3] > which contains the built documentation. > Just open build/html/index.html (you can even test the search page if you > want). > > advantages of using Sphinx are: > - simple to use > - simple to build > - proven technology (the python documentation - and many others - are > powered by Sphinx) > - can be "themed" so the UI can be consistent with the Rsyslog website > - easy to deploy, simple HTML files > > The only drawback I see is that the documentation needs to be > converted, but this is far for being hard. > > I would like to get your feedback about this experiment. > Do you think migrating the actual doc to a Sphinx based doc is worth it ? > I believe this would make it easier to use the documentation and make > rsyslog a bit easier to use for beginners. > We could even merge the wiki and the documentation in order to get one > source of documentation. > > Have a nice day :) > > 1. http://sphinx-doc.org/ > 2. http://johnmacfarlane.net/pandoc/ > 3. build.tar.gz > > -- > Jérôme > > _______________________________________________ > 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.
