Mailinglist Archive: opensuse-buildservice (250 mails)

< Previous Next >
Re: [opensuse-buildservice] BuildService documentation not acceptable
  • From: "Petit Eric" <surfzoid@xxxxxxxxx>
  • Date: Thu, 28 Aug 2008 17:21:21 +0200
  • Message-id: <84776a970808280821h69cb640pda927e0019cc2125@xxxxxxxxxxxxxx>
2008/8/28 Archie Cobbs <archie@xxxxxxxxxxxx>:
On Thu, Aug 28, 2008 at 7:33 AM, Dirk Stöcker <opensuse@xxxxxxxxxxxx> wrote:
On Thu, 28 Aug 2008, Andreas Jaeger wrote:
The minimum I would expect ist that the page
http://en.opensuse.org/Category:Build_Service

has entries to relevant information or to a link list pointing to further
non-wiki information.

It's a wiki. Fell free to add the missing parts.

Michael, is there enough documentation that he can do it? Can you point
Dirk to some of it so that he can consolidate that information? Or do
you expect him to read the source code?

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? Especially if these
others are an commercial company.

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.

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.

Even worse, as a new user the last thing you want to do is to distract
the experts who are working hard to provide this great service with
annoying newbie questions.
I think you speak of the client side and specialy the WebClient.
You also have osc cmd line tool, but the "expert" area seems only edit
XML data by the hand, i writted MonoOSC, not yed finish, but perhap's
you will think it 's easiest for newbie, without go in extrmly
complicated setting :
http://sourceforge.net/projects/monoosc/
Also im curently writting developper docs for those want to use the
wrapper of OBS API i writted in C# , a first preview can be see here :
http://surfzoid.free.fr/freevbsoft/MonoOSC/Docs/

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.

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.

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.

Clearly Novell can dedicate a couple of resources to this task. It
even makes obvious business sense, because OBS is a powerful
differentiating technology for Novell. So why limit it's potential
because of such a silly reason?

-Archie

--
Archie L. Cobbs
---------------------------------------------------------------------
To unsubscribe, e-mail: opensuse-buildservice+unsubscribe@xxxxxxxxxxxx
For additional commands, e-mail: opensuse-buildservice+help@xxxxxxxxxxxx





--

Cordially.

Small Eric Quotations of the days:
---------------------------------------------------------------------------
If one day one reproaches you that your work is not a work of
professional, say you that:
Amateurs built the arch of Noah, and professionals the Titanic.
---------------------------------------------------------------------------

Few people are done for independence, it is the privilege of the powerful ones.
---------------------------------------------------------------------------

No key was wounded during the drafting of this message.
---------------------------------------------------------------------
To unsubscribe, e-mail: opensuse-buildservice+unsubscribe@xxxxxxxxxxxx
For additional commands, e-mail: opensuse-buildservice+help@xxxxxxxxxxxx

< Previous Next >