Mailing List Archive: rsyslog documentation

rsyslog documentation

Nov 26, 2008, 3:20 AM

Post #1 of 10 (4175 views)

Hi all,

as you probably know, I keep rsyslog's documentation in html files, with
the man pages containing the bare minimum to make sense of the system.
This need arises from the sheer volume of the information that must be
provided.

However, this makes the documentation pretty closed (everything needs to
go through me) and consequently I have seen very few doc contributions.
It probably also makes it more complicated than needed to translate the
documentation.

Initially, I considered a purely web-based doc vs. a html-file based
doc. I went for the file-based doc as this can easily be distributed
together with every rsyslog version.

However, looking at other projects, many have adapted a web-based
approach where version differences are flagged within the documentation.
The advantage of a web-based doc is that we can use thinks like a wiki
to generate it. That, I think, would make it much easier for users to
contribute doc or at least samples. Also, it looks like a web-based doc
is also more convenient for most users. Everyone has a browser open and
checks the web, but who installs doc packages? ;)

So I am now consider changing to a web-based system, too. I'd probably
consider the rsyslog wiki (http://wiki.rsyslog.com) a good starting
point. Since I created it, it receives a slow but steady traffic
increase and has now around the same number of hits than the rsyslog
main site. I would move over the current file-based doc into that system
and at the same time see that I can improve the structure and usability
of the doc.

With the many new and powerful features that appeared in rsyslog over
the past couple of month, I think it is very important to make them
accessible by a sufficiently good doc. The current one is, to phrase it
politely, not good. It probably even hinders adoption of rsyslog in some
cases.

With a web-based system open to user contributions I hope to solve this
issues.

Please let me know your thoughts. All feedback is deeply appreciated.

Many thanks,
Rainer Gerhards

_______________________________________________
rsyslog mailing list
http://lists.adiscon.net/mailman/listinfo/rsyslog
http://www.rsyslog.com

Re: rsyslog documentation [ In reply to ]

mbiebl at gmail

Nov 26, 2008, 4:10 AM

Post #2 of 10 (4074 views)

Permalink

2008/11/26 Rainer Gerhards <rgerhards@hq.adiscon.com>:
>
> However, looking at other projects, many have adapted a web-based
> approach where version differences are flagged within the documentation.
> The advantage of a web-based doc is that we can use thinks like a wiki
> to generate it. That, I think, would make it much easier for users to
> contribute doc or at least samples. Also, it looks like a web-based doc
> is also more convenient for most users. Everyone has a browser open and
> checks the web, but who installs doc packages? ;)
>
> So I am now consider changing to a web-based system, too. I'd probably
> consider the rsyslog wiki (http://wiki.rsyslog.com) a good starting
> point. Since I created it, it receives a slow but steady traffic
> increase and has now around the same number of hits than the rsyslog
> main site. I would move over the current file-based doc into that system
> and at the same time see that I can improve the structure and usability
> of the doc.
>
> With the many new and powerful features that appeared in rsyslog over
> the past couple of month, I think it is very important to make them
> accessible by a sufficiently good doc. The current one is, to phrase it
> politely, not good. It probably even hinders adoption of rsyslog in some
> cases.
>
> With a web-based system open to user contributions I hope to solve this
> issues.
>
> Please let me know your thoughts. All feedback is deeply appreciated.

Imho it would be very unfortunate, if the documentation would only be
available online.

A wiki can be a very good *additional* source of documentation (for
stuff like best practices, tips and tricks), but it doesn't substitute
a well written manual.

What I would rather like to see (and I know, I'm repeating myself
here), is to have the existing documentation a bit more structured and
easier accessible. I posted examples like the exim [1] or postgresql
[2] documentation, which I think are excellent.

The postgresql documentation is interesting. If you follow [2] the
link, you can see, that users are able to add comments, which could be
helpful to improve the overall documentation.
There is still a "static" version though, also available as pdf, which
you could print and even use as a book.

Cheers,
Michael

[1] http://www.exim.org/exim-html-current/doc/html/spec_html/index.html
http://www.exim.org/exim-pdf-current/doc/spec.pdf
[2] http://www.postgresql.org/docs/8.3/interactive/index.html
--
Why is it that all of the instruments seeking intelligent life in the
universe are pointed away from Earth?
_______________________________________________
rsyslog mailing list
http://lists.adiscon.net/mailman/listinfo/rsyslog
http://www.rsyslog.com

Re: rsyslog documentation [ In reply to ]

mbiebl at gmail

Nov 26, 2008, 4:16 AM

Post #3 of 10 (4078 views)

Permalink

2008/11/26 Michael Biebl <mbiebl@gmail.com>:
>
> The postgresql documentation is interesting. If you follow [2] the
> link, you can see, that users are able to add comments, which could be
> helpful to improve the overall documentation.
> There is still a "static" version though, also available as pdf, which
> you could print and even use as a book.

And distribute easily with the rsyslog release tarball

Cheers,
Michael

P.S: Maybe a book could be an additional source of income.

--
Why is it that all of the instruments seeking intelligent life in the
universe are pointed away from Earth?
_______________________________________________
rsyslog mailing list
http://lists.adiscon.net/mailman/listinfo/rsyslog
http://www.rsyslog.com

Re: rsyslog documentation [ In reply to ]

rfujita at redhat

Nov 26, 2008, 4:18 AM

Post #4 of 10 (4078 views)

Permalink

Hi all,

> [1] http://www.exim.org/exim-html-current/doc/html/spec_html/
> index.html
> http://www.exim.org/exim-pdf-current/doc/spec.pdf
> [2] http://www.postgresql.org/docs/8.3/interactive/index.html

Both these links are made with DocBook.

Best Rio.

On 2008/11/26, at 21:10, Michael Biebl wrote:

> 2008/11/26 Rainer Gerhards <rgerhards@hq.adiscon.com>:
>>
>> However, looking at other projects, many have adapted a web-based
>> approach where version differences are flagged within the
>> documentation.
>> The advantage of a web-based doc is that we can use thinks like a
>> wiki
>> to generate it. That, I think, would make it much easier for users to
>> contribute doc or at least samples. Also, it looks like a web-based
>> doc
>> is also more convenient for most users. Everyone has a browser open
>> and
>> checks the web, but who installs doc packages? ;)
>>
>> So I am now consider changing to a web-based system, too. I'd
>> probably
>> consider the rsyslog wiki (http://wiki.rsyslog.com) a good starting
>> point. Since I created it, it receives a slow but steady traffic
>> increase and has now around the same number of hits than the rsyslog
>> main site. I would move over the current file-based doc into that
>> system
>> and at the same time see that I can improve the structure and
>> usability
>> of the doc.
>>
>> With the many new and powerful features that appeared in rsyslog over
>> the past couple of month, I think it is very important to make them
>> accessible by a sufficiently good doc. The current one is, to
>> phrase it
>> politely, not good. It probably even hinders adoption of rsyslog in
>> some
>> cases.
>>
>> With a web-based system open to user contributions I hope to solve
>> this
>> issues.
>>
>> Please let me know your thoughts. All feedback is deeply appreciated.
>
> Imho it would be very unfortunate, if the documentation would only be
> available online.
>
> A wiki can be a very good *additional* source of documentation (for
> stuff like best practices, tips and tricks), but it doesn't substitute
> a well written manual.
>
> What I would rather like to see (and I know, I'm repeating myself
> here), is to have the existing documentation a bit more structured and
> easier accessible. I posted examples like the exim [1] or postgresql
> [2] documentation, which I think are excellent.
>
> The postgresql documentation is interesting. If you follow [2] the
> link, you can see, that users are able to add comments, which could be
> helpful to improve the overall documentation.
> There is still a "static" version though, also available as pdf, which
> you could print and even use as a book.
>
> Cheers,
> Michael
>
>
> [1] http://www.exim.org/exim-html-current/doc/html/spec_html/
> index.html
> http://www.exim.org/exim-pdf-current/doc/spec.pdf
> [2] http://www.postgresql.org/docs/8.3/interactive/index.html
> --
> Why is it that all of the instruments seeking intelligent life in the
> universe are pointed away from Earth?
> _______________________________________________
> rsyslog mailing list
> http://lists.adiscon.net/mailman/listinfo/rsyslog
> http://www.rsyslog.com

########################################################################
Ryo Fujita <rfujita@redhat.com>
Senior Solution Architect, RHCE
Red Hat K.K.
TEL +81-3-5798-8500
FAX +81-3-5798-8599
Ebisu Neonato 8F
4-1-18 Ebisu, Shibuya-ku,
Tokyo Japan 1500013
########################################################################

_______________________________________________
rsyslog mailing list
http://lists.adiscon.net/mailman/listinfo/rsyslog
http://www.rsyslog.com

Re: rsyslog documentation [ In reply to ]

rfujita at redhat

Nov 26, 2008, 4:19 AM

Post #5 of 10 (4093 views)

Permalink

Hi,

> P.S: Maybe a book could be an additional source of income.

+1

Best Rio.

On 2008/11/26, at 21:16, Michael Biebl wrote:

> 2008/11/26 Michael Biebl <mbiebl@gmail.com>:
>>
>> The postgresql documentation is interesting. If you follow [2] the
>> link, you can see, that users are able to add comments, which could
>> be
>> helpful to improve the overall documentation.
>> There is still a "static" version though, also available as pdf,
>> which
>> you could print and even use as a book.
>
> And distribute easily with the rsyslog release tarball
>
> Cheers,
> Michael
>
> P.S: Maybe a book could be an additional source of income.
>
>
> --
> Why is it that all of the instruments seeking intelligent life in the
> universe are pointed away from Earth?
> _______________________________________________
> rsyslog mailing list
> http://lists.adiscon.net/mailman/listinfo/rsyslog
> http://www.rsyslog.com

########################################################################
Ryo Fujita <rfujita@redhat.com>
Senior Solution Architect, RHCE
Red Hat K.K.
TEL +81-3-5798-8500
FAX +81-3-5798-8599
Ebisu Neonato 8F
4-1-18 Ebisu, Shibuya-ku,
Tokyo Japan 1500013
########################################################################

_______________________________________________
rsyslog mailing list
http://lists.adiscon.net/mailman/listinfo/rsyslog
http://www.rsyslog.com

Re: rsyslog documentation [ In reply to ]

mrdemeanour at jackpot

Nov 26, 2008, 4:24 AM

Post #6 of 10 (4069 views)

Permalink

Michael Biebl wrote:
>>
>> With a web-based system open to user contributions I hope to solve
>> this issues.
>>
>> Please let me know your thoughts. All feedback is deeply
>> appreciated.
>
> Imho it would be very unfortunate, if the documentation would only be
> available online.

+1.

Many projects now use Docbook, to generate variously HTML, PDF and manpages.

On most of my servers, I have no X GUI set up; HTML docs are therefore a
pain in the neck, unless the HTML is extremely clean (and even then it's
a hassle).

The documentation should be a part of the project, and it should be
possible to check it out, modify it (e.g. translate it) and 'build' it.

I think wiki docs are great, but I also think the foundation for a
documentation wiki should be the authorised version of the docs. Users
can then comment on that authorised version, which should be the docs
that ship with the product. It might be possible to rig some mechanism
for automagically pulling content from the wiki back into the
repository; but I'm not sure how to go about that.

Thanks for this excellent project, and for being so committed to it!
--
Jack.
_______________________________________________
rsyslog mailing list
http://lists.adiscon.net/mailman/listinfo/rsyslog
http://www.rsyslog.com

Re: rsyslog documentation [ In reply to ]

rgerhards at hq

Nov 26, 2008, 4:28 AM

Post #7 of 10 (4080 views)

Permalink

Hi Michael,

thanks for the feedback.

On Wed, 2008-11-26 at 13:10 +0100, Michael Biebl wrote:
> Imho it would be very unfortunate, if the documentation would only be
> available online.
>
> A wiki can be a very good *additional* source of documentation (for
> stuff like best practices, tips and tricks), but it doesn't substitute
> a well written manual.
>
> What I would rather like to see (and I know, I'm repeating myself
> here), is to have the existing documentation a bit more structured and
> easier accessible. I posted examples like the exim [1] or postgresql
> [2] documentation, which I think are excellent.

I think the PHP manual is also a good sample.

But actually this doesn't solve my main point: It is quite
time-consuming to create a good doc. I am ready to put a bit more time
into that (moving that away from development), but I would like to
encourage user contributions. Without bashing, it is one thing to show a
good example, but it is a totally different one to provide good
content ;)

The bottom line is that I know I could do better, but I have not
sufficient time (and probably not the best talent in that area) to
actually do it.

> The postgresql documentation is interesting. If you follow [2] the
> link, you can see, that users are able to add comments, which could be
> helpful to improve the overall documentation.

This is the main point. Maybe I can find a way to easily make user
comments available to the current doc set. That would help drive in user
contributions (at least I hope so). The problem again is that I simply
can not invest a few weeks of my time "just" to get the right doc
display system done.

It's a trade-off between time available, hoping to get contributions and
quality of doc.

Again, I value your thoughts very much, they go in the same direction of
what I hope to have, but it looks like I currently can not achieve this
and need to lower my demands in order to get working, solution - but one
that is better than the current state...

Rainer

_______________________________________________
rsyslog mailing list
http://lists.adiscon.net/mailman/listinfo/rsyslog
http://www.rsyslog.com

Re: rsyslog documentation [ In reply to ]

rgerhards at hq

Nov 26, 2008, 4:43 AM

Post #8 of 10 (4075 views)

Permalink

Hi all,

some times it seems to help ask around ;) Andre who cares for the web
sites (also the phpLogCon lead devel) has pointed out to me that we may
try the CMS' comment function. We have now enabled that. It seems to
solve the immediate need. So this looks like a way we can at least try
out.

Anyhow, if you have any additional thoughts please let me know them.
They probably help shape a medium-term doc strategy.

Thanks,
Rainer

On Wed, 2008-11-26 at 13:28 +0100, Rainer Gerhards wrote:
> Hi Michael,
>
> thanks for the feedback.
>
> On Wed, 2008-11-26 at 13:10 +0100, Michael Biebl wrote:
> > Imho it would be very unfortunate, if the documentation would only be
> > available online.
> >
> > A wiki can be a very good *additional* source of documentation (for
> > stuff like best practices, tips and tricks), but it doesn't substitute
> > a well written manual.
> >
> > What I would rather like to see (and I know, I'm repeating myself
> > here), is to have the existing documentation a bit more structured and
> > easier accessible. I posted examples like the exim [1] or postgresql
> > [2] documentation, which I think are excellent.
>
> I think the PHP manual is also a good sample.
>
> But actually this doesn't solve my main point: It is quite
> time-consuming to create a good doc. I am ready to put a bit more time
> into that (moving that away from development), but I would like to
> encourage user contributions. Without bashing, it is one thing to show a
> good example, but it is a totally different one to provide good
> content ;)
>
> The bottom line is that I know I could do better, but I have not
> sufficient time (and probably not the best talent in that area) to
> actually do it.
>
> > The postgresql documentation is interesting. If you follow [2] the
> > link, you can see, that users are able to add comments, which could be
> > helpful to improve the overall documentation.
>
> This is the main point. Maybe I can find a way to easily make user
> comments available to the current doc set. That would help drive in user
> contributions (at least I hope so). The problem again is that I simply
> can not invest a few weeks of my time "just" to get the right doc
> display system done.
>
> It's a trade-off between time available, hoping to get contributions and
> quality of doc.
>
> Again, I value your thoughts very much, they go in the same direction of
> what I hope to have, but it looks like I currently can not achieve this
> and need to lower my demands in order to get working, solution - but one
> that is better than the current state...
>
> Rainer
>
> _______________________________________________
> rsyslog mailing list
> http://lists.adiscon.net/mailman/listinfo/rsyslog
> http://www.rsyslog.com

_______________________________________________
rsyslog mailing list
http://lists.adiscon.net/mailman/listinfo/rsyslog
http://www.rsyslog.com

Re: rsyslog documentation [ In reply to ]

david at lang

Nov 26, 2008, 9:57 AM

Post #9 of 10 (4080 views)

Permalink

On Wed, 26 Nov 2008, Michael Biebl wrote:

> 2008/11/26 Rainer Gerhards <rgerhards@hq.adiscon.com>:
>>
>> However, looking at other projects, many have adapted a web-based
>> approach where version differences are flagged within the documentation.
>> The advantage of a web-based doc is that we can use thinks like a wiki
>> to generate it. That, I think, would make it much easier for users to
>> contribute doc or at least samples. Also, it looks like a web-based doc
>> is also more convenient for most users. Everyone has a browser open and
>> checks the web, but who installs doc packages? ;)
>>
>> So I am now consider changing to a web-based system, too. I'd probably
>> consider the rsyslog wiki (http://wiki.rsyslog.com) a good starting
>> point. Since I created it, it receives a slow but steady traffic
>> increase and has now around the same number of hits than the rsyslog
>> main site. I would move over the current file-based doc into that system
>> and at the same time see that I can improve the structure and usability
>> of the doc.
>>
>> With the many new and powerful features that appeared in rsyslog over
>> the past couple of month, I think it is very important to make them
>> accessible by a sufficiently good doc. The current one is, to phrase it
>> politely, not good. It probably even hinders adoption of rsyslog in some
>> cases.
>>
>> With a web-based system open to user contributions I hope to solve this
>> issues.
>>
>> Please let me know your thoughts. All feedback is deeply appreciated.
>
> Imho it would be very unfortunate, if the documentation would only be
> available online.

I definantly agree. whatever is done online needs to have some way of
having a snapshot of it done to be distributed for offline access.

> A wiki can be a very good *additional* source of documentation (for
> stuff like best practices, tips and tricks), but it doesn't substitute
> a well written manual.

the other problem with a wiki is that unless you have the time to review
the changes there is a real risk that the documentation will be wrong.
this is true of any user-contributed documentation, but with a wiki there
is no way for other users to know what has been checked and is correct vs
what is wrong.

the suggestion elsewhere in this thread to have an authoritative source
with the ability for people to make comments does a good job of
differentiating between the two.

David Lang

> What I would rather like to see (and I know, I'm repeating myself
> here), is to have the existing documentation a bit more structured and
> easier accessible. I posted examples like the exim [1] or postgresql
> [2] documentation, which I think are excellent.
>
> The postgresql documentation is interesting. If you follow [2] the
> link, you can see, that users are able to add comments, which could be
> helpful to improve the overall documentation.
> There is still a "static" version though, also available as pdf, which
> you could print and even use as a book.
>
> Cheers,
> Michael
>
>
> [1] http://www.exim.org/exim-html-current/doc/html/spec_html/index.html
> http://www.exim.org/exim-pdf-current/doc/spec.pdf
> [2] http://www.postgresql.org/docs/8.3/interactive/index.html
>
_______________________________________________
rsyslog mailing list
http://lists.adiscon.net/mailman/listinfo/rsyslog
http://www.rsyslog.com

Re: rsyslog documentation [ In reply to ]

hks.private at gmail

Nov 26, 2008, 12:20 PM

Post #10 of 10 (4072 views)

Permalink

On Wed, Nov 26, 2008 at 7:43 AM, Rainer Gerhards
<rgerhards@hq.adiscon.com> wrote:
> Hi all,
>
> some times it seems to help ask around ;) Andre who cares for the web
> sites (also the phpLogCon lead devel) has pointed out to me that we may
> try the CMS' comment function. We have now enabled that. It seems to
> solve the immediate need. So this looks like a way we can at least try
> out.
>
> Anyhow, if you have any additional thoughts please let me know them.
> They probably help shape a medium-term doc strategy.
>
> Thanks,
> Rainer

I agree with most contributors so far, that a typical user-contributed
wiki alone is not sufficient. For a perfect example of a great project
crippled by abysmal wiki documentation, see OpenNMS.

Wikis /can/ work as official documentation, provided that they are
carefully thought through and official sources are the main
contributors. A general structure also needs to be in place so that
things don't spread out into a web of maze-like links with multiple
pages describing the same subject, albeit with small and crucial
differences. Their main benefits are, obviously, some measure of
self-correction and allowing users to share their solutions to
problems the developers may not have encountered.

Don't know if that helps, but I hope so.

-HKS
_______________________________________________
rsyslog mailing list
http://lists.adiscon.net/mailman/listinfo/rsyslog
http://www.rsyslog.com