New TOC structure

[rgerhards]

We need a new TOC structue that is easy to follow and appealing to beginners. @radu-gheorghe already made a suggestion, which I have put into the repo:

https://github.com/rsyslog/rsyslog-doc/blob/master/proposed-toc

We should work on that proposal in order to get closer to a final version. Alternatively, we can implement it and make changes as we go along. Comments and feedback both on the process as well as the actual TOC are appreciated. If no comments occur, we probably go ahead and begin to implement the propsal.

[ribeiropaulor]

Has any new structure been worked on? If not, could we move forward with this discussion? I started using Rsyslog. I really like it, but the documentation sucks, IMHO. I have some experience with Sphinx I could help with this big change in documentation.

[ribeiropaulor]

Following is my proposal as my first attempt to better the documentation. I stored in an Github repository (https://github.com/gruvo/rsyslog-doc-pt-BR/tree/v8-stable/source/proposals/new_documentation). I restructured the existing information in the form of a book, a cookbook, a configuration reference and auxiliary sections.

I guess it should not be difficult to get it done. I offer myself for this job.

Please review this proposal. I appreciate your feedback.

[ribeiropaulor]

Rsyslog Documentation Review Proposal

Currently the Rsyslog documentation is spread over many places. It's not logical and well-organized as well. The objective of this proposal is to address those issues and establish a procedure for further development of the documentation.

We SHOULD NOT write examples using mixed formats, RainerScripts and legacy. It confused
the readers. We can provide them in both formats, but should not mix them.

Compile information from current sources of information

Below are listed the official locations where documentation about Rsyslog can be found.

* Wiki: http://wiki.rsyslog.com/index.php/Main_Page
* Rainer's blog: http://blog.gerhards.net/2012/10/how-to-use-rsyslogs-ruleset-and-call.html
* Issues: https://github.com/rsyslog/rsyslog
* docs: https://github.com/rsyslog/rsyslog-doc
* Forum: http://kb.monitorware.com/configuration-f36.html

Add a Cookbook Section

We should create some cookbooks to help people get started with Rsyslog. Some candidates to be a cookbook are below.

* http://sickbits.net/log-storage-and-analysis-infrastructure-reliable-logging-and-analysis-with-rsyslog-and-relp/
* http://kb.monitorware.com/omfile-with-dynfile-syslogfacility-text-t12515.html
* http://www.freeipa.org/page/Howto/Centralised_Logging_with_Logstash/ElasticSearch/Kibana

Add a subsection called "processing logs from". We'd place articles that'd would help people with specific common scenarios for a specific log sender application.

Add a Reference Section

This section would have all the reference configuration of all possibile tags, in both formats, RainerScript and legacy.

Write articles that address common problems

Some of the common are following.

* https://github.com/rsyslog/rsyslog/issues/160
* http://kb.monitorware.com/nginx-logging-rsyslog-t12359.html
* http://trac.nginx.org/nginx/ticket/677

Proposed Documentation Structure

[radu-gheorghe]

Thanks for putting effort into this. It looks good to me, I guess it's just a matter of working on it (which is a huge task and I, for example, don't have the guts to take on it) and then the ToC will be readjusted as we go along.

Maybe an idea for the "huge work" problem is just to break down the mega-workload into smaller and smaller pieces that each of us could take when we have a bit of time. Again, even dividing the thing is quite a challenge :)

Regarding the legacy config formats: in my mind, this is a huge drag in the current documentation. Many people don't even know about the new format, and even when they do, they're feeling familiar with the old one and stick to it. The new format is around for years, and I'm not sure if new, old-style options are added. If they aren't (or maybe not a lot of new significant options), and idea could be to only document the new style in the documentation for version 8 and later. We can add a note saying "looking for the old config format? Take a look at the old version's docs". This way we proactively encourage people to upgrade their configs to the new format and save us a lot of maintenance work. Which would be already huge.

[ribeiropaulor]

You're right. The job to be done is huge. I'll start working on this first step: split into smaller pieces of work.

How do you think is best to work on the new documentation? Right now it's in another repository (the one that, in the future, should hold the Brazilian Portuguese translated version). I think I should move those files to a fork of this main repository still under the folder /proposals/new_documentation and push changes from there. Do you agree?

[rgerhards]

Hi, let me chime in. I am unfortunately busy with some other stuff, but I really like the idea of getting the doc restructured. Looks like a great proposal! As @radu-gheorghe said, I wouldn't spend too much time on the legacy format, we strongly recommend NOT to use it for anything that requires setting parameters.

On the repo: from my PoV, it works best if you fork the repro and create pull requests from there. But any other mode will also work, of course. We can track this in a separate branch (e.g. "big_doc_change" or so). And when it is ready for prime time, we can simply merge it into master.

[ribeiropaulor]

Ok. I'll do that!

[ribeiropaulor]

Could you please create the branch big_restructuring from master so I can create a pull request?

[rgerhards]

done! thanks again for looking into this, very much appreciated.

[ribeiropaulor]

The preview of restructuring can be accessed on

http://rsyslog-doc.readthedocs.org/en/big_restructuring/proposals/big_restructuring/index.html

[mostolog]

PR done while ago: https://github.com/rsyslog/rsyslog-doc/pull/188