Mailinglist Archive: yast-devel (116 mails)

< Previous Next >
Re: [yast-devel] YaST Workshop 2008
  • From: Stefan Hundhammer <sh@xxxxxxx>
  • Date: Tue, 24 Jun 2008 15:48:17 +0200
  • Message-id: <200806241548.17393.sh@xxxxxxx>
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 <sh@xxxxxxx> Penguin by conviction.
YaST2 Development
SUSE LINUX Products GmbH, GF: Markus Rex, HRB 16746 (AG Nürnberg)
Nürnberg, Germany
--
To unsubscribe, e-mail: yast-devel+unsubscribe@xxxxxxxxxxxx
For additional commands, e-mail: yast-devel+help@xxxxxxxxxxxx

< Previous Next >
Follow Ups