Dirk Stöcker wrote:

Hello,

now I'm with the build service from the very beginning and know a lot stuff how to use it, but this week I wanted to try something new and needed documentation for it.

It is impossible to find anything useful about buildservice project configuration:/

a) I wanted to know how to use Prefer:, Substitute:, Ignore: and all the others. There is no documenation on the wiki pages and also nowhere else a I tried was a link to helpful information. But when I know what I search and after hours don't find anything, a beginner will fail totally.

Part of it is there, on the Tips and Tricks page: http://en.opensuse.org/Build_Service/Tips_and_Tricks#How_is_a_buildenvironme... . But I agree that the existing documentation is hard to navigate :-(. Michal --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-buildservice+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-buildservice+help@opensuse.org

Alexey Eremenko wrote:

...

. But I agree that the existing documentation is hard to navigate :-(.

Then it should be added to "contrib" :)

It also solves problem of what-is-hard-to-navigate

Can you elaborate? How does packaging a copy of incomplete wiki documentation solve anything? Michal --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-buildservice+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-buildservice+help@opensuse.org

Michael Schroeder <mls@suse.de> writes:

On Thu, Aug 28, 2008 at 10:30:43AM +0200, Dirk Stöcker 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? Andreas -- Andreas Jaeger, Director Platform / openSUSE, aj@suse.de SUSE LINUX Products GmbH, GF: Markus Rex, HRB 16746 (AG Nürnberg) Maxfeldstr. 5, 90409 Nürnberg, Germany GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126

On Thu, Aug 28, 2008 at 7:33 AM, Dirk Stöcker <opensuse@dstoecker.de> 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. 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@opensuse.org For additional commands, e-mail: opensuse-buildservice+help@opensuse.org

Am Donnerstag, 28. August 2008 16:58:37 schrieb Archie Cobbs:

On Thu, Aug 28, 2008 at 7:33 AM, Dirk Stöcker <opensuse@dstoecker.de> 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@opensuse.org For additional commands, e-mail: opensuse-buildservice+help@opensuse.org

On Fri, Aug 29, 2008 at 02:00:58PM +0200, Klaas Freitag wrote:

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.

I hesitate to chime in here, since this is a controversial topic, but I so strongly disagree with the above, that I must respond. I'm not saying this to tell people what to do with their time, or to tell Novell what to do with their resources. I just want to point out that this task is relatively straightforward, since the community tells you how to do it, if you're looking. Any developer good at his job is good at organizing things, and documentation is just one more set of code, but written in English or German instead of C or Python. The table of contents is your main() function. Anyone who spends much time on the mailing list answering questions, or in the irc channel helping people with spec files, will have the weak areas of the documention pointed out to him. If it is not possible to completely answer a user's question with a URL pointing to a page in the manual, then the manual needs work. If there are only one or two people doing the bulk of question answering, it will eventually get to the point that it is easier to answer questions once in a manual than multiple times on the mailing list. New users need: 1) An overview This has to be high level, birds-eye view. It needs to tell the user what the pieces are, how all the pieces fit together, what things are assumed, and what things the user must supply. For example, when I started out, I had the hardest time figuring out how to tell the system which file was my spec file. An overview that told me that the server automatically scans for *.spec and *.dsc files after every commit would have helped ease the pain. Instead, it was a patient and helpful irc user who told me. 2) A reference This is an organized, outlined list of features that are available in the server, the client, any libraries, etc. Every feature is listed, in its proper section, with a description of what it does, why it is needed, how to use it, and an example. 3) A tutorial This consists of one example, of varying complexity, taking the user's hand and going one step at a time, showing a piece of the spec file, and showing the solution to any problems encountered. One way to do this would be to look at the commit history of a new, small project committed by a new user, and describe the steps and pitfalls he encountered. Again, any newbie questions that keep coming up on the mailing list or irc indicate places to improve the tutorial. 4) Examples Ideally these examples: - are embedded in the reference - exist as one large example in the tutorial - have a spot in source control for a variety of sample spec files, and listed in an appendix of the documentation 5) One location for _ALL_ of the above There should be one outline from overview to examples, with links to each section, page, and example. I think this is OBS's sticky point... some of the above items are already done, but it's just not organized on one page with a comprehensive outline, guiding new users through the maze. And the great thing is that this doesn't have to happen all at once. And if there is one place for this in source control, people can send patches to it as if it were code. To get the ball rolling, the following decisions and actions need to be made: 1) What format to write it in If you want contributions from everyone, it should be something that many people know how to write. Maybe more people know HTML than DocBook? Pick something everyone knows how to write. 2) Who is responsible for adding documentation submitted by users? Sometimes a user might be willing to write some paragraphs on how to use a feature he just figured out, but won't be willing to write it in the XML manual format you chose. Have them write the docs in a simple email, and have a Document Wrangler paste it into the right section, and format it. When asking for a user to write a paragraph or two, point them at the outline, and ask them to write section 1.2.3. Sometimes their issue or question may prompt an update to the outline itself. 3) Setup a process where the source control is automatically built The manual needs to be updated, live on the website, straight from source control. An outline is a great help here, with long lists of sections of features that are not documented yet, but at least listed. I'm sure there are developers would could make a list of features in various sections of the system, and this can be organized into an outline. As users hit those roadblocks, each section is filled in. Harness the newbie questions, and with a little thought and planning, they will guide you to creating excellent documentation. More information on documentation can be found here: http://producingoss.com/en/getting-started.html#documentation Even look at the table of contents of that book: http://producingoss.com/en/index.html OBS needs a table of contents like that, even if the links don't point anywhere yet. - Chris --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-buildservice+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-buildservice+help@opensuse.org

On Thu, Aug 28, 2008 at 09:58:37AM -0500, Archie Cobbs wrote:

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.

There appears to be a skeleton of a book on the build service in SVN already: https://forgesvn1.novell.com/svn/opensuse In the trunk, under documentation/books/en/xml It looks like it is in DocBook format. It doesn't appear like this is available online though. It would be cool if it was, so people could send patches to this book, and it would update on the web automatically. - Chris --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-buildservice+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-buildservice+help@opensuse.org

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

On Sun, Aug 31, 2008 at 08:27:51PM -0500, Archie Cobbs wrote:

I think with more "publicity" it should get some needed attention and contributions.

I've added a link to it from the Build Service wiki front page. - Chris --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-buildservice+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-buildservice+help@opensuse.org