Mailinglist Archive: opensuse-buildservice (250 mails)

< Previous Next >
Re: [opensuse-buildservice] BuildService documentation not acceptable
  • From: Carsten Hoeger <choeger@xxxxxxxxxxxxxxxx>
  • Date: Fri, 29 Aug 2008 18:02:11 +0200
  • Message-id: <20080829160211.GK4085@xxxxxxxxxxxxxxxx>
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.

[...]

What is needed is an "OBS reference manual". Ideally, it should be
included in the source repository and all changes to OBS should
include updates to the documentation as well (a "live" document).
There are tons of examples of other open source projects doing this
and plenty of tools out there that support doing it.
Again I agree completely. Maintaining the documentation in the source repo
is the only way to produce documentation that goes along the product.

But to write good user documentation about the BS it requires more
than just having it in the source repo. Such a documentation needs
professional editing, a good concept, ongoing proofreading etc.

[...]

Well, I don't think so.
Incomplete or bad documentation is always better then no documentation at all.

It's like bad press is better then no press... :-)

--
With best regards,

Carsten Hoeger
< Previous Next >
Follow Ups