Am Freitag, 29. August 2008 18:02:11 schrieb Carsten Hoeger: Hi Choeger,
On Fri, Aug 29, Klaas Freitag wrote:
I don't mind reading source code to document, but I plainly don't have the time to document openSUSE BuildService. I don't find lots of time to document my own stuff, so why should I do so for things others made?
If that's your mindset you should think again if free software projects are the right place for you to be.
Especially if these others are an commercial company.
This opinion, again, is the reason for many problems we have in the project. It's poor.
Although I do exactly know, why documentation is often lacking in many free software projects, I think a projects owner cannot expect it's users to document the project. To document a project, a user has to have the knowledge of the project creator or a developer with deep knowledge. Or the user has to spend a lot of time to dig into that project. You cannot expect that from most of the users. So if the intent of a free software project is to spread fast, it should at least have basic documentation. Of course I do not expect people to document the project, I know that the project needs better documentation and I don't want to push away our responsibility. Please don't misunderstand me. All I wanted to point out is that working on documentation is a very neccessary, welcome and valueable contribution to the project that is doable without programming knowledge. And as we can and should work together on code we can do it on documentation.
Let's say that documentation is one of the very weak points of the whole OBS. Especially than it makes no sense only to point to 'Novell' and put pressure on the teams. We did not do the docs well the last three years, so I see very little likelihood that this improves dramatically now, for human factor. If someone or something has weak sides I think it is more constructive to jump in and give a little help in that area than putting more pressure on. Followup mails in this thread did the right thing and gave very constructive help, thanks :-) Of course one could ask and wait for Novell to fix the situation. But I doubt that this will benefit our project.
What is needed is an "OBS reference manual". For a start, please check out https://build.opensuse.org/documentation/obs/index.html which I built and deployed a few minutes ago and will take care that this will happen regularly now.
This is a book about the buildservice started by the SUSE documentation team under the Lessons for Lizards initiative. For various reasons they are not able to put a lot of work on it. The sources can be found under https://forgesvn1.novell.com/svn/opensuse/trunk/buildservice/documentation It's docbook, but its doable for people with basic xml knowledge I think. To build it, do the following steps: - check out the above - install the rpm susedoc calling "sudo zypper in susedoc" - cd books/en - source the build service preferences: ". ./ENV-Build_Service" - build the book: call "make" or "make html" If you have patches, please send them to the list or in pm to me. If docbook does not come handy, just send your patches in plain text and I am happy to apply them.
It's like bad press is better then no press... :-) Hehe, I know this strategy, did you read my latest mails on this list? ;-)
Klaas -- Klaas Freitag Architect OPS/IPD SUSE LINUX Products GmbH - Nuernberg --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-buildservice+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-buildservice+help@opensuse.org