[yast-devel] YaST Workshop 2008
Hi all, first of all I'd like to thank you for the hard work on openSUSE 11.0, it's definitely going to be a great release! Having said that I'm pleased to announce YaST Workshop 2008, taking place in Nuremberg, June 30 to July 4. The main goal is to move YaST further, both in terms of functionality, but also higher flexibility and more openness. We want to give developers a chance to work on something new, something we often neglected for some time, something cool and also have fun with that. The details about the workshop can be found here: http://en.opensuse.org/YaST/Events/Workshop_Nuremberg_2008 As it is supposed to be a team work, I'd like to encourage you to have a look at the ideas, enlist yourself at those you would like to work on and use the time until the workshop to look around the topics and learn new things, possibly using your ITO. The list of ideas is not closed so anybody can expand the list with further ideas. Also, if you would like to work with a collegue from a different team or department on the project, feel free to invite him to take a part (and let us know in order to prepare the logistics). I strongly believe this would be fun and useful as well and I'm looking forward to it. Thanks Michal -- To unsubscribe, e-mail: yast-devel+unsubscribe@opensuse.org For additional commands, e-mail: yast-devel+help@opensuse.org
Michal Švec wrote:
The main goal is to move YaST further, both in terms of functionality, but also higher flexibility and more openness. We want to give developers a chance to work on something new, something we often neglected for some time, something cool and also have fun with that.
The details about the workshop can be found here: http://en.opensuse.org/YaST/Events/Workshop_Nuremberg_2008
As it is supposed to be a team work, I'd like to encourage you to have a look at the ideas, enlist yourself at those you would like to work on and use the time until the workshop to look around the topics and learn new things, possibly using your ITO. The list of ideas is not closed so anybody can expand the list with further ideas.
Hi, I've already added two "new" projects [1],[2] and I'd like to encourage you, developers, to add the project you would like to work on or a project you think might really help YaST to become even more useful and user-friendly. Nobody should force you to work on "Using CIM from YaST modules" or "YaST web user interface" if you don't like to work on these projects, but, for instance, "YaST on other Distributions" sounds promising, doesn't it? :) Please, try to read through the current projects and pick some and/or write your own there: http://en.opensuse.org/YaST/Research It would be also nice if you could write your name to the project you want to work on. If you are unsure, talk to others about it. [1] YaST Interface for Webpin http://en.opensuse.org/YaST/Research/YaST_Interface_for_Webpin [2] YaST Style Guide http://en.opensuse.org/YaST/Research/YaST_Style_Guide Have a nice day Lukas
Hi, This is Pearly Zhao from Oracle Linux team. I'm working on porting YaST to RHEL4/EL4 and RHEL5/EL5. The site of YaST on RHEL/EL is at http://oss.oracle.com/projects/yast/. About YaST on RHEL/EL, only the main modules and some modules we needed are ported. YaST on RHEL4/EL4 has been opened to download and YaST on RHEL5/EL5 will be uploaded soon. The codes will be contributed as soon as possible too. I think the codes and experience can help YaST on Fedora or other distributions. So I would like to work on "YaST on other Distributions" http://en.opensuse.org/YaST/Research/YaST_on_other_Distributions Best Regards Pearly Zhao Oracle Linux engineer Lukas Ocilka wrote:
Michal Švec wrote:
The main goal is to move YaST further, both in terms of functionality, but also higher flexibility and more openness. We want to give developers a chance to work on something new, something we often neglected for some time, something cool and also have fun with that.
The details about the workshop can be found here: http://en.opensuse.org/YaST/Events/Workshop_Nuremberg_2008
As it is supposed to be a team work, I'd like to encourage you to have a look at the ideas, enlist yourself at those you would like to work on and use the time until the workshop to look around the topics and learn new things, possibly using your ITO. The list of ideas is not closed so anybody can expand the list with further ideas.
Hi,
I've already added two "new" projects [1],[2] and I'd like to encourage you, developers, to add the project you would like to work on or a project you think might really help YaST to become even more useful and user-friendly.
Nobody should force you to work on "Using CIM from YaST modules" or "YaST web user interface" if you don't like to work on these projects, but, for instance, "YaST on other Distributions" sounds promising, doesn't it? :)
Please, try to read through the current projects and pick some and/or write your own there: http://en.opensuse.org/YaST/Research It would be also nice if you could write your name to the project you want to work on. If you are unsure, talk to others about it.
[1] YaST Interface for Webpin http://en.opensuse.org/YaST/Research/YaST_Interface_for_Webpin [2] YaST Style Guide http://en.opensuse.org/YaST/Research/YaST_Style_Guide
Have a nice day Lukas
-- To unsubscribe, e-mail: yast-devel+unsubscribe@opensuse.org For additional commands, e-mail: yast-devel+help@opensuse.org
On Wed, Jun 18, 2008 at 02:19:15PM +0800, Zhao Shujing wrote:
Hi,
This is Pearly Zhao from Oracle Linux team. I'm working on porting YaST to RHEL4/EL4 and RHEL5/EL5. The site of YaST on RHEL/EL is at http://oss.oracle.com/projects/yast/.
About YaST on RHEL/EL, only the main modules and some modules we needed are ported. YaST on RHEL4/EL4 has been opened to download and YaST on RHEL5/EL5 will be uploaded soon. The codes will be contributed as soon as possible too.
I think the codes and experience can help YaST on Fedora or other distributions. So I would like to work on "YaST on other Distributions" http://en.opensuse.org/YaST/Research/YaST_on_other_Distributions
Hi Pearly, good to hear that! Would you like to come over to Nuremberg for the workshop? Yes, I realize that it is a long way and short notice. I looked at http://oss.oracle.com/projects/yast/ last year and I was somewhat dissappointed seeing that you were using yast2-2.9.x. That is old, it comes from SLES9, released in 2004, and we released SLES10 in 2006 already. Yesterday openSUSE 11.0 came out having yast2-2.16.x, and SLES 11 will have 2.17.x. I mean, if you use a code base that is too old, it will not be possible to merge your patches to the current development tree. I understand that you have already started porting for RHEL5, right? Can you share the source/patches with us? Join us on IRC: irc://irc.opensuse.org/yast for a more direct conversation. -- Martin Vidner, YaST developer http://en.opensuse.org/User:Mvidner Kuracke oddeleni v restauraci je jako fekalni oddeleni v bazenu -- To unsubscribe, e-mail: yast-devel+unsubscribe@opensuse.org For additional commands, e-mail: yast-devel+help@opensuse.org
On 06/20/2008 04:59 PM, Martin Vidner wrote:
On Wed, Jun 18, 2008 at 02:19:15PM +0800, Zhao Shujing wrote:
Hi,
This is Pearly Zhao from Oracle Linux team. I'm working on porting YaST to RHEL4/EL4 and RHEL5/EL5. The site of YaST on RHEL/EL is at http://oss.oracle.com/projects/yast/.
About YaST on RHEL/EL, only the main modules and some modules we needed are ported. YaST on RHEL4/EL4 has been opened to download and YaST on RHEL5/EL5 will be uploaded soon. The codes will be contributed as soon as possible too.
I think the codes and experience can help YaST on Fedora or other distributions. So I would like to work on "YaST on other Distributions" http://en.opensuse.org/YaST/Research/YaST_on_other_Distributions
Hi Pearly,
good to hear that! Would you like to come over to Nuremberg for the workshop? Yes, I realize that it is a long way and short notice.
I looked at http://oss.oracle.com/projects/yast/ last year and I was somewhat dissappointed seeing that you were using yast2-2.9.x. That is old, it comes from SLES9, released in 2004, and we released SLES10 in 2006 already. Yesterday openSUSE 11.0 came out having yast2-2.16.x, and SLES 11 will have 2.17.x. I mean, if you use a code base that is too old, it will not be possible to merge your patches to the current development tree.
I understand that you have already started porting for RHEL5, right? Can you share the source/patches with us?
Join us on IRC: irc://irc.opensuse.org/yast for a more direct conversation.
Hi, Martin Thanks for your invitation, but for some personal reason, I can't go to Nuremberg to attend the workshop. Porting YaST to RHEL/EL is for an Oracle product Oracle Enterprise Manager, so we have to use the same version YaST between SLES9 and RHEL4/EL4, though it is old. YaST for RHEL5/EL5 is ported from the version of SLES10SP1 and it is in testing now. I will share the sources/patches when it is finished. Best Regards Pearly -- To unsubscribe, e-mail: yast-devel+unsubscribe@opensuse.org For additional commands, e-mail: yast-devel+help@opensuse.org
Lukas Ocilka wrote:
Nobody should force you to work on "Using CIM from YaST modules" or "YaST web user interface" if you don't like to work on these projects, but, for instance, "YaST on other Distributions" sounds promising, doesn't it? :)
Please, try to read through the current projects and pick some and/or write your own there: http://en.opensuse.org/YaST/Research It would be also nice if you could write your name to the project you want to work on. If you are unsure, talk to others about it.
Hi, As I saw, some of you have already written yourself under some of the projects, that's nice! Thanks ;) What isn't so nice is a fact that I saw a lot of "willing mentors" but almost nobody who would like to "really work" on that project. Why is that? It seems that developers are either not interested in those projects listed or they would like maximally mentor someone? See, the YaST Workshops starts in ten days! Bye Lukas
Lukas Ocilka wrote:
What isn't so nice is a fact that I saw a lot of "willing mentors" but almost nobody who would like to "really work" on that project. Why is that? It seems that developers are either not interested in those projects listed or they would like maximally mentor someone?
A new project has been added: "Make Building YaST Documentation Easier (Better)" @see http://en.opensuse.org/YaST/Research It's actually not only about building the documentation but also about the documentation in general. I hope someone will take this opportunity to work on something that really *makes sense* :))) ;) Bye Lukas
On Friday 20 June 2008 13:53, Lukas Ocilka wrote:
A new project has been added: "Make Building YaST Documentation Easier (Better)" @see http://en.opensuse.org/YaST/Research
It's actually not only about building the documentation
...good so far. Because that aspect would only affect one single person, so it's not really something worthwhile for all YaST2 hackers to do. Even though, of course, that one person would probably see that differently. ;-)
but also about the documentation in general.
Well, yes. But I don't see a problem in the form in which the documentation is
available (web page, Wiki or PDF - who really cares?), but in the stuff that
_is_ documented. The last time I was seriously searching some documtation I
found that ~70% of all documentation is the UI documentation that I once
wrote, while other aspects are still largely undocumented (YCP built-ins or
SCR comes to mind).
But is that something we can fix in a couple of days worth of workshop?
CU
--
Stefan Hundhammer
Stefan Hundhammer wrote:
but also about the documentation in general.
Well, yes. But I don't see a problem in the form in which the documentation is available (web page, Wiki or PDF - who really cares?), but in the stuff that _is_ documented. The last time I was seriously searching some documtation I found that ~70% of all documentation is the UI documentation that I once wrote, while other aspects are still largely undocumented (YCP built-ins or SCR comes to mind).
But is that something we can fix in a couple of days worth of workshop?
What about just starting it? If you don't have a better project, pick this one :) At least, developers should know that and how they should document their code, their API. @see Source Code Documentation HowTo http://forgeftp.novell.com/yast/doc/SL11.0/tdg/Book-Documentation.html Moreover, I saw a lot of "Hey, the current documentation is boring, I have a brand-new idea how to make it much better with a little effort"s ... but what was the result? ENOTIME? Documentation? Who cares? I also saw some requirements from external developers to download a PDF version of our documentation in the past so they actually really care. I could search yast-devel or some internal mailing-list where I are asked developers to document their code and how (for instance SCR docu), but that will not be necessary, I guess. Documentation is vitally important if we want to port YaST to other distributions (*HINT!*). L.
On Fri, Jun 20, 2008 at 03:29:24PM +0200, Lukas Ocilka wrote:
Stefan Hundhammer wrote:
But is that something we can fix in a couple of days worth of workshop?
What about just starting it? If you don't have a better project, pick this one :) At least, developers should know that and how they should document their code, their API.
@see Source Code Documentation HowTo http://forgeftp.novell.com/yast/doc/SL11.0/tdg/Book-Documentation.html
Moreover, I saw a lot of "Hey, the current documentation is boring, I have a brand-new idea how to make it much better with a little effort"s ... but what was the result? ENOTIME? Documentation? Who cares? I also saw some requirements from external developers to download a PDF version of our documentation in the past so they actually really care. I could search yast-devel or some internal mailing-list where I are asked developers to document their code and how (for instance SCR docu), but that will not be necessary, I guess.
Documentation is vitally important if we want to port YaST to other distributions (*HINT!*).
My pet issue with the documentation is its structuring. With a proper one, one could neatly divide it into packages, have pieces of it drop in... Here is a prototype: http://www.suse.de/~mvidner/refdoc-prototype/ -- Martin Vidner, YaST developer http://en.opensuse.org/User:Mvidner Kuracke oddeleni v restauraci je jako fekalni oddeleni v bazenu -- To unsubscribe, e-mail: yast-devel+unsubscribe@opensuse.org For additional commands, e-mail: yast-devel+help@opensuse.org
On Friday 20 June 2008 17:26, Martin Vidner wrote:
My pet issue with the documentation is its structuring. With a proper one, one could neatly divide it into packages, have pieces of it drop in... Here is a prototype: http://www.suse.de/~mvidner/refdoc-prototype/
I agree.
The monster document known as "The Definite Guide" is useful if you want to
read all documentation, or if you want to get an overview what documentation
is available at all. But it's pure hell to search for anything, in particular
if you have a rough idea where it is. I have a hard time finding my own UI
reference documentation there...
CU
--
Stefan Hundhammer
Stefan Hundhammer wrote:
On Friday 20 June 2008 17:26, Martin Vidner wrote:
My pet issue with the documentation is its structuring. With a proper one, one could neatly divide it into packages, have pieces of it drop in... Here is a prototype: http://www.suse.de/~mvidner/refdoc-prototype/
I agree.
The monster document known as "The Definite Guide" is useful if you want to read all documentation, or if you want to get an overview what documentation is available at all. But it's pure hell to search for anything, in particular if you have a rough idea where it is. I have a hard time finding my own UI reference documentation there...
I personally use only these pieces: * YCP Modules * SCR Agents * Reference — YCP Language * Reference — User Interface I'd easily drop all those monster documents. We should think about what developers want and need. If you can't find your documentation, try one-file-documentation, there you can see what is the documentation all about: http://forgeftp.novell.com/yast/doc/SL11.0/onefile/ (Well, 6 files, but you'll definitely find it). Bye Lukas
On Monday 23 June 2008 10:47:14 Lukas Ocilka wrote:
Stefan Hundhammer wrote:
On Friday 20 June 2008 17:26, Martin Vidner wrote:
My pet issue with the documentation is its structuring. With a proper one, one could neatly divide it into packages, have pieces of it drop in... Here is a prototype: http://www.suse.de/~mvidner/refdoc-prototype/
I agree.
The monster document known as "The Definite Guide" is useful if you want to read all documentation, or if you want to get an overview what documentation is available at all. But it's pure hell to search for anything, in particular if you have a rough idea where it is. I have a hard time finding my own UI reference documentation there...
I personally use only these pieces:
* YCP Modules
In most cases I need only modules from yast2.rpm, I suggest to separate modules from this package, or show also needed dependency for each module. M. -- To unsubscribe, e-mail: yast-devel+unsubscribe@opensuse.org For additional commands, e-mail: yast-devel+help@opensuse.org
Michal Zugec wrote:
On Monday 23 June 2008 10:47:14 Lukas Ocilka wrote:
I personally use only these pieces:
* YCP Modules
In most cases I need only modules from yast2.rpm, I suggest to separate modules from this package, or show also needed dependency for each module.
Very nice, finally, the very first volunteer raised his voice to really *do* something about the documentation. Thanks a lot! For others: Even the documentation is *open-source* :) whatever it actually means - you see the code, and you can change it! ;) http://svn.opensuse.org/svn/yast/trunk/doc/ Showing the RPM-dependencies in YCP/Perl modules is a good start. *thumbs up* Lukas
On Friday 20 June 2008 15:29, Lukas Ocilka wrote:
I also saw some requirements from external developers to download a PDF version of our documentation in the past
You mean: Some die-hard IBM engineers who learned their trade back in the late
sixties and who are used to *printed* documentation that is measured in shelf
meters? ;-)
Frankly, I wouldn't know what format would be even less useful than PDF for
this kind of documentation (just think about hyperlinks etc.). Well, WordStar
2000 maybe. ;-)
CU
--
Stefan Hundhammer
Stefan Hundhammer wrote:
On Friday 20 June 2008 15:29, Lukas Ocilka wrote:
I also saw some requirements from external developers to download a PDF version of our documentation in the past
You mean: Some die-hard IBM engineers who learned their trade back in the late sixties and who are used to *printed* documentation that is measured in shelf meters? ;-)
Now you're hurting others feelings :) There must be a reason for having PDF version. What about taking that printed document with you on a holiday? Do you have any better idea what to do during weekends off-line that reading some monster document :) aha?
Frankly, I wouldn't know what format would be even less useful than PDF for this kind of documentation (just think about hyperlinks etc.). Well, WordStar 2000 maybe. ;-)
PDF can handle hyperlinks, but not the printed one, of course. L.
Stefan Hundhammer wrote:
Well, yes. But I don't see a problem in the form in which the documentation is available (web page, Wiki or PDF - who really cares?), but in the stuff that _is_ documented. The last time I was seriously searching some documtation I found that ~70% of all documentation is the UI documentation that I once wrote, while other aspects are still largely undocumented (YCP built-ins or SCR comes to mind).
YCP builtins are documented and would have useful examples if anybody cared when writing them: http://forgeftp.novell.com/yast/doc/SL11.0/tdg/Book-YaSTReference.html SCR Agents are documented quite well (yes, developers don't comment their code and don't write correct headers for agents, that should be better too): http://forgeftp.novell.com/yast/doc/SL11.0/scr/index.html but we should have better (more useful) documentation for SCR in general: http://forgeftp.novell.com/yast/doc/SL11.0/onefile/yast-onefile.html#the_scr... http://forgeftp.novell.com/yast/doc/SL11.0/tdg/id_big_architecture.html#the_... http://forgeftp.novell.com/yast/doc/SL11.0/onefile/yast-onefile.html#Book-SC... http://forgeftp.novell.com/yast/doc/SL11.0/tdg/Book-SCRDetails.html There are at least two ways how to define importance of a document. The first measurable value is "the length", the second one is "amount of information" inside. Who, for instance, reads the AutoYaST documentation? http://forgeftp.novell.com/yast/doc/SL11.0/autoinstall/index.html http://forgeftp.novell.com/yast/doc/SL11.0/autoinstall/devel/index.html These are useful pieces of information that YaST developers should know... Lukas
On Monday 23 June 2008 10:58, Lukas Ocilka wrote:
YCP builtins are documented and would have useful examples if anybody cared when writing them:
http://forgeftp.novell.com/yast/doc/SL11.0/tdg/Book-YaSTReference.html
AFAICS that documentation is just the bare minimum - little more than the function name. And the examples are not really explanatory. Some newer built-ins are documented a lot better (e.g., splitstring()). But that's the exceptional case. Worst, the most powerful built-ins are not documented in a way any novice YCP developer can make sense of anything: http://forgeftp.novell.com/yast/doc/SL11.0/tdg/YCPBuiltinList_filter.html http://forgeftp.novell.com/yast/doc/SL11.0/tdg/YCPBuiltinList_find.html http://forgeftp.novell.com/yast/doc/SL11.0/tdg/YCPBuiltinList_foreach.html http://forgeftp.novell.com/yast/doc/SL11.0/tdg/YCPBuiltinList_listmap.html http://forgeftp.novell.com/yast/doc/SL11.0/tdg/YCPBuiltinList_maplist.html Some docs lack basic things like "will the original object be modified?" (old-time YCP hackers of course know, but can we expect that from newbies?): http://forgeftp.novell.com/yast/doc/SL11.0/tdg/YCPBuiltinList_remove.html And why a built-in called setcontains() handles lists, not sets, is completely unclear: http://forgeftp.novell.com/yast/doc/SL11.0/tdg/YCPBuiltinList_setcontains.ht...
SCR Agents are documented quite well
Uh - no. I find the documentation of most of them utterly useless.
http://forgeftp.novell.com/yast/doc/SL11.0/scr/1.anyxml.html
http://forgeftp.novell.com/yast/doc/SL11.0/scr/2.audio.html
http://forgeftp.novell.com/yast/doc/SL11.0/scr/3.autoyast2.desktop.html
http://forgeftp.novell.com/yast/doc/SL11.0/scr/5.backup.file_append.html
http://forgeftp.novell.com/yast/doc/SL11.0/scr/9.bootloader.html
http://forgeftp.novell.com/yast/doc/SL11.0/scr/10.complain.html
http://forgeftp.novell.com/yast/doc/SL11.0/scr/14.cron.html
...
(only ~1 out of 10 has anything meaningful at all)
If we want community developers to contribute and use our infrastructure, that
infrastructure must be reasonably usable. And that starts with documentation.
CU
--
Stefan Hundhammer
Stefan Hundhammer wrote:
On Monday 23 June 2008 10:58, Lukas Ocilka wrote:
YCP builtins are documented and would have useful examples if anybody cared when writing them:
http://forgeftp.novell.com/yast/doc/SL11.0/tdg/Book-YaSTReference.html
AFAICS that documentation is just the bare minimum - little more than the function name. And the examples are not really explanatory.
That's what I actually blame YaST-core maintainer for. Anyway, anybody who has write access to our SVN can change it and add some missing pieces, e.g., explanatory examples. You might have seen some of my commits that were just adding comments to some other's code. You can do the same... everybody can...
Some newer built-ins are documented a lot better (e.g., splitstring()). But that's the exceptional case.
Worst, the most powerful built-ins are not documented in a way any novice YCP developer can make sense of anything:
http://forgeftp.novell.com/yast/doc/SL11.0/tdg/YCPBuiltinList_filter.html http://forgeftp.novell.com/yast/doc/SL11.0/tdg/YCPBuiltinList_find.html http://forgeftp.novell.com/yast/doc/SL11.0/tdg/YCPBuiltinList_foreach.html http://forgeftp.novell.com/yast/doc/SL11.0/tdg/YCPBuiltinList_listmap.html http://forgeftp.novell.com/yast/doc/SL11.0/tdg/YCPBuiltinList_maplist.html
cd source/core/libycp/src svn blame YCPBuiltinList.cc YCPBuiltinString.cc YCPBuiltinTerm.cc
Some docs lack basic things like "will the original object be modified?" (old-time YCP hackers of course know, but can we expect that from newbies?):
http://forgeftp.novell.com/yast/doc/SL11.0/tdg/YCPBuiltinList_remove.html
And why a built-in called setcontains() handles lists, not sets, is completely unclear:
http://forgeftp.novell.com/yast/doc/SL11.0/tdg/YCPBuiltinList_setcontains.ht...
Anas :)? heh
SCR Agents are documented quite well
Uh - no. I find the documentation of most of them utterly useless.
http://forgeftp.novell.com/yast/doc/SL11.0/scr/1.anyxml.html http://forgeftp.novell.com/yast/doc/SL11.0/scr/2.audio.html http://forgeftp.novell.com/yast/doc/SL11.0/scr/3.autoyast2.desktop.html http://forgeftp.novell.com/yast/doc/SL11.0/scr/5.backup.file_append.html http://forgeftp.novell.com/yast/doc/SL11.0/scr/9.bootloader.html http://forgeftp.novell.com/yast/doc/SL11.0/scr/10.complain.html http://forgeftp.novell.com/yast/doc/SL11.0/scr/14.cron.html ...
(only ~1 out of 10 has anything meaningful at all)
Report a bug or even fix it ;) I usually do it that way...
If we want community developers to contribute and use our infrastructure, that infrastructure must be reasonably usable. And that starts with documentation.
That's also why I've added this project: Make YaST Documentation Better http://en.opensuse.org/YaST/Research/Make_Building_YaST_Documentation_Easier...) Feel free to add yourself to the project if you are willing to help. Bye Lukas
On Tuesday 24 June 2008 13:58, Lukas Ocilka wrote:
Stefan Hundhammer wrote:
On Monday 23 June 2008 10:58, Lukas Ocilka wrote:
YCP builtins are documented and would have useful examples if anybody cared when writing them:
http://forgeftp.novell.com/yast/doc/SL11.0/tdg/Book-YaSTReference.html
AFAICS that documentation is just the bare minimum - little more than the function name. And the examples are not really explanatory.
That's what I actually blame YaST-core maintainer for. Anyway, anybody who has write access to our SVN can change it and add some missing pieces, e.g., explanatory examples.
Lukas, just to clarify: I am not blaming you for the lack of documentation of such essential things. Maintaining documentation generation (which is what you agreed to AFAIK) is a one important task. This does not include writing documentation for all the things where docs are missing. Writing or adding missing docs is the responsibility of the author of the respective piece of software or of the maintainer. I find it really sad to see that in all the years of using YCP nobody found it important enough to write decent documentation to such basic things as YCP built-ins or SCR agents. IMHO it is the first and most important thing to do when writing a new piece of software to describe what it should do. That's the specification, the guideline for coding. Done properly, this should serve a dual purpose as documentation. I've been doing this for years and years, and I always found that approach worthwhile. Not only does that generate documentation as a nice side effect, it also forces you to think about what that function should do, what the parameters are, how fringe cases (NULL or nil) are handled, and what values are returned. Example: http://svn.opensuse.org/svn/yast/trunk/libyui/src/YSelectionWidget.h IMHO this is the way to go for C++ as well as for YCP or for other things that have only the most remote chance to be used from anybody else (but I do it also for functions that are used purely internally). IMHO this is so natural that I am wondering how others are coping with their programming interfaces. How would I know in six weeks from now what on earth some function does, what parameters it expects, what it returns in all cases? How are the authors of all those undocumented SCR agents doing it? Is there some documentation hidden in some other place? I can't believe it's all throw-away code - written just for here and now, meant to be reengineered for every tiny little change. There must be some methodical approach to it that I just don't see. So how does it work?
You might have seen some of my commits that were just adding comments to some other's code. You can do the same... everybody can...
Sure. I could. But frankly, why would I want to reward those who didn't do the most basic requirement of their job in the first place? Documenting is part of the development process. This might sound harsh, but IMHO those who don't do it just don't do their job right - it's just being lazy. And pressing release milestones is something that affects us all, so that cannot hold as an excuse for all eternity - even less so when summarizing what a function does is to all intents and purposes a time saver, not additional time spent.
SCR Agents are documented quite well
Uh - no. I find the documentation of most of them utterly useless.
http://forgeftp.novell.com/yast/doc/SL11.0/scr/1.anyxml.html ... http://forgeftp.novell.com/yast/doc/SL11.0/scr/14.cron.html
(only ~1 out of 10 has anything meaningful at all)
Report a bug or even fix it ;) I usually do it that way...
The most basic clicking through that agents list (that's what I did in my previous mail) will show that the great majority of them has little or no documentation.
If we want community developers to contribute and use our infrastructure, that infrastructure must be reasonably usable. And that starts with documentation.
That's also why I've added this project: Make YaST Documentation Better http://en.opensuse.org/YaST/Research/Make_Building_YaST_Documentation_Easie r_(Better)
Feel free to add yourself to the project if you are willing to help.
No, I am not going to write other people's documentation on top of all the
stuff I already documented. Not only no, but "hell, no". ;-}
CU
--
Stefan Hundhammer
Stefan Hundhammer wrote:
Lukas, just to clarify: I am not blaming you for the lack of documentation of such essential things. Maintaining documentation generation (which is what you agreed to AFAIK) is a one important task. This does not include writing documentation for all the things where docs are missing.
I was a bit afraid it had turned to blaming the only one who responds. Thanks for your clarification :) ;) But as far as I can see, there's nobody other interested. "Who needs documentation anyway?" Anybody else? Should I care and build it for every release? Try to enhance it? Add some most-painfully missing pieces bit by bit?
... ... ...
If we want community developers to contribute and use our infrastructure, that infrastructure must be reasonably usable. And that starts with documentation. That's also why I've added this project: Make YaST Documentation Better http://en.opensuse.org/YaST/Research/Make_Building_YaST_Documentation_Easie r_(Better)
Feel free to add yourself to the project if you are willing to help.
No, I am not going to write other people's documentation on top of all the stuff I already documented. Not only no, but "hell, no". ;-}
Hmm, yes, that seems to be logically a better approach. Kids, it's your turn now. Lukas PS: The project mentioned above is not only about "writing a missing documentation" nor about "enhancing building the documentation". It's about documentation in general: missing/wanted features, structure, searching, understandability, writing tutorials, writing FAQ, adding examples, linking examples, ... there is a lot of work to do.
On Fri, 20 Jun 2008, Lukas Ocilka wrote:
What isn't so nice is a fact that I saw a lot of "willing mentors" but almost nobody who would like to "really work" on that project. Why is that? It seems that developers are either not interested in those projects listed or they would like maximally mentor someone?
It is a good point, please try to apply for the projects you are intested in ASAP so we can see how it looks like and possibly discuss that. There is a "Participants" field in each project for this. Regarding mentors, for the workshop I'd say they are more like a list of people with knowledge, if they would be involved more I'd say thay should be listed as participants.
See, the YaST Workshops starts in ten days!
Correct :-) Thanks Michal -- To unsubscribe, e-mail: yast-devel+unsubscribe@opensuse.org For additional commands, e-mail: yast-devel+help@opensuse.org
Lukas Ocilka wrote:
As I saw, some of you have already written yourself under some of the projects, that's nice! Thanks ;)
What isn't so nice is a fact that I saw a lot of "willing mentors" but almost nobody who would like to "really work" on that project. Why is that? It seems that developers are either not interested in those projects listed or they would like maximally mentor someone?
See, the YaST Workshops starts in ten days!
Thanks for adding your project to the YaST/Research page! http://en.opensuse.org/YaST/Research#YaST_Interface_for_Webpin These project have been added recently: * CVS/SVN for System Config Files * Signals and Slots for Libzypp * YaST Libzypp module * YaST module using mod_ui directly * (K)Desktop Integration for plug'n'play Hardware It seems things are starting to move. Anyway, it's time you advertised your projects among others to get the needed support. In my opinion, work goes better in groups than if a single person does it. Moreover single-person projects are not allowed this time :) ;) Thx && Bye Lukas
participants (7)
-
Lukas Ocilka -
Martin Vidner -
Michal Svec -
Michal Zugec -
Michal Švec
-
Stefan Hundhammer -
Zhao Shujing