[opensuse-buildservice] BuildService documentation not acceptable
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. b) I tried to find out how to change the package version. I know there exists a method to do so and I also know it has been discussed multiple times on this list. Only after I scanned the obs sources I found the way it works using <CI_CNT>.<B_CNT> and this helps to scan this list for the mails. 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. Ciao -- http://www.dstoecker.eu/ (PGP key available) --------------------------------------------------------------------- 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 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. Cheers, Michael. -- Michael Schroeder mls@suse.de SUSE LINUX Products GmbH, GF Markus Rex, HRB 16746 AG Nuernberg main(_){while(_=~getchar())putchar(~_-1/(~(_|32)/13*2-11)*13);} --------------------------------------------------------------------- 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, 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. Ciao -- http://www.dstoecker.eu/ (PGP key available) --------------------------------------------------------------------- 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 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
2008/8/28 Archie Cobbs <archie@dellroad.org>:
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. 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@opensuse.org For additional commands, e-mail: opensuse-buildservice+help@opensuse.org
-- 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@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, 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
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 3:37 PM, Klaas Freitag <freitag@suse.de> wrote:
What is needed is an "OBS reference manual". For a start, please check out https://build.opensuse.org/documentation/obs/index.html
This is exactly what is needed -- thanks for publishing it (I didn't know it existed). I think with more "publicity" it should get some needed attention and contributions. -Archie -- Archie L. Cobbs --------------------------------------------------------------------- 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
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 Fri, 29 Aug 2008, Chris Frey wrote:
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 do as well, but I really think the stuff below really needs to be done.
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.
+1 -- Boyd Gerber <gerberb@zenez.com> ZENEZ 1042 East Fort Union #135, Midvale Utah 84047 --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-buildservice+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-buildservice+help@opensuse.org
On Fri, 29 Aug 2008, 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.
Before you blame somebody not to support OpenSource check who you blame. If I enter your name in Google I find only one reference called Kooka. Check my name same way. I think more than 15 years of open source software programming should be enough to have my own opinion about what I do and what not!
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.
This is a perfect valid opinion. Novell is a commercial company and everthing I do in the BuildService helps Novell direct or indirect. I also have positive effects from this, or I would not do what I do. But don't expect me to dedicate my soul to commercial interests, as this would be really poor. I'm old enough to seperate my private and commercial interests. The BuildService becomes a central part of the SUSE distribution and you expect me to write documentation for it?
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.
You talk nonsense. What you talk about is a end-user documentation. Nobody asked for this. Required is a minimum documentation. Which keywords are supported in which places, which functions are supported, what effects do they have, where are the configurations and so on. This is plain task of any developer. Has always been. This plain documentation I'm required to make always for our own software as well. And I'm sure there are already parts of this, but it cannot be found which actually means it does not exist really.
Clearly Novell can dedicate a couple of resources to this task. This is currently not happening.
Yes, we see that. Ciao -- http://www.dstoecker.eu/ (PGP key available) --------------------------------------------------------------------- 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
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
. 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 -- -Alexey Eromenko "Technologov" --------------------------------------------------------------------- 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
On Thu, Aug 28, 2008 at 12:04 PM, Michal Marek <mmarek@suse.cz> wrote:
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?
That was a joke - don't take it seriously -- -Alexey Eromenko "Technologov" --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-buildservice+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-buildservice+help@opensuse.org
participants (11)
-
Alexey Eremenko -
Andreas Jaeger -
Archie Cobbs -
Boyd Lynn Gerber -
Carsten Hoeger -
Chris Frey -
Dirk Stöcker -
Klaas Freitag -
Michael Schroeder -
Michal Marek -
Petit Eric