On Wed, 26 Nov 2008, Michael Biebl wrote: > 2008/11/26 Rainer Gerhards <[EMAIL PROTECTED]>: >> >> 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
