Mailinglist Archive: opensuse-buildservice (250 mails)

< Previous Next >
Re: [opensuse-buildservice] BuildService documentation not acceptable
  • From: Klaas Freitag <freitag@xxxxxxx>
  • Date: Fri, 29 Aug 2008 14:00:58 +0200
  • Message-id: <200808291400.58720.freitag@xxxxxxx>
Am Donnerstag, 28. August 2008 16:58:37 schrieb Archie Cobbs:

On Thu, Aug 28, 2008 at 7:33 AM, Dirk Stöcker <opensuse@xxxxxxxxxxxx> 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.

I have to chime in with a "me too" here... warning: strong opinion
follows...

The OBS is an amazing project, and I think it has the potential to
improve not only SUSE Linux but all versions of Linux in a meaningful
and positive way. It also makes openSUSE more versatile than other
distributions.
Thanks. This is my opinion as well.

However, when I started using it I was quite shocked that it is so
hard to figure out what is going on. People refer to all these
mysterious settings and mechanisms on the mailing list, but they are
not documented anywhere (findably). I was perfectly willing and eager
to read the whole official OBS reference manual... except that it
didn't exist.
You're right.

In my opinion this is a dangerous barrier to the success of this
project... because like any other "network effect" project, the more
people utilize and contribute to OBS the more valuable it will be.
This project, like any other, needs to encourage new members and make
them feel welcome instead of making them feel confused and like
they're just being annoying.
Yes, again I agree completely. We're somehow limiting the people who
can and will use the BS by that. That's a very limiting factor.

In a perfect world, yes, the wiki would grow and organize itself.
Clearly, that's not happening though... or at least, the wiki is not
addressing the need completely.
I do not think a wiki is suitable for the kind of documentation needed
for the BS.

So in my opinion this projects needs to STOP for a minute and think
about how to improve 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.
That is doable, but not from developers who work on the code. They
(we) simply can not do that, not only because we're usually bad writer,
but because we simply do not see where documentation is needed. As
the developer of a part of the system, all seems so obvious that
one thinks it is not neccessary to document it decently. As features
sum up, things get messy.

How is that solvable? There have to be documentation editors who watch
what the developers are doing. If features show up, they have to stand
up and TALK to the developers and ask them questions. With that input
they can write good documentation. Developers can proofread, comment
etc.

I think working on that would be a very valueable contribution to
the project, doable without or with little coding experience.
Waiting for Novell to jump in because Novell sponsors the project
will fail.

Clearly Novell can dedicate a couple of resources to this task.
This is currently not happening.

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 >