Mailinglist Archive: opensuse-buildservice (250 mails)

< Previous Next >
Re: [opensuse-buildservice] BuildService documentation not acceptable
  • From: Klaas Freitag <freitag@xxxxxxx>
  • Date: Sun, 31 Aug 2008 22:37:40 +0200
  • Message-id: <200808312237.40598.freitag@xxxxxxx>
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@xxxxxxxxxxxx
For additional commands, e-mail: opensuse-buildservice+help@xxxxxxxxxxxx

< Previous Next >