Benoit St-Pierre wrote:
Hi!
> Here is why I stopped working on help.tcl :
>
> Almost all pages are too long. Topics need tightening.
> Information suffers from being outdated.
>
> Well, we just can not have 1000 features and absoultely no
> comment how to use them. This is not possible. It can not be
> that even me, really following the development of the app,
> have no clue at all about some options, just as there is not
> a word lost about them. It can not be that we refer a user
> to a technical ChangeLog or to the list archive.
>
> This does adress anything to what I am talking about. It uses what I
> am talking about to speak about what you want to talk about.
>
> This is the same thing as saying : A is not the problem, B is the
> problem, when A and B are thoroughly unrelated.
Sorry, I do not get the argument. Maybe this way. Till
yestereve we had Play / Training / Openings. Joe User comes
along, "Ah, an opening trainer, interesting! Lets try that
thing." An there Joe is lost. Not even the ChangeLog said a
word about what is required for it and the help page
(accessible once you got it up...) only explained the
statistics. You might remember, we had some lengthy thread
here, while ago, about how to get it working, and before that
I think I had some (private?) communication with Pascal,
simply cause I thought it is bound to the Reperoire Editor,
which is (according to the docs) the way to store your
opening repertoire in Scid. But it isn't...
Same goes for almost all new functions. We have a lot of
them but don't say a word about how they can be used.
This has, in fact, nothing to do with the length or design
of the pages as such, or how it is stored technically. Anyway,
you may be sure that I even edited quite a bunch of
"unrelated" pages, ie. updated information in quite some
related or linked pages and cleand up several outdated
information as well. Currently, Scids help features about 60
pages, 23 of them now are "Updated for 3.6.26".
Still, 63 lines of documentation relevant changelog to go. I
started at about 300 lines. (Took about 2h to just extract
what is relevant from the ChangeLog. We can not refer a user
to this...)
Anyway, if you want to come up with a better system for
handling all this: please do so. If you want (and have the
time) to even rewrite it from scratch, its fine with me as
well. If you want to reformat all of this, the same, if you
want to straighten the texts, well feel free.
For the moment I admit I'd be happy, if we have some
instructions for all our functions.
> This is not communication.
I agree with you that there is a certain lack of
communication between development of new features and
documentation. As I already said, I'd find it very helpful,
if new functions are introduced if at least the dialogues
got a hook up for F1 and an (empty) stub for the page to
come in help.tcl. And I also agree that it would be most
helpful for some other writer to have at least a rough
layout of the function (s)he should describe in those stubs.
Besides, at the moment I'm trying to clean up outdated stuff
in the docs and add descriptions for all functions there.
I do not say that I do a perfect job here, I may still miss
some points, or miss to describe a function. Surely,
sometimes even the text can be done better. (But well, a
german documentation has a value close to 0, there're not
enough people out there that speak this strange language ;)
So, feel free to shape it up. Still I feel it is a pressing
issue to get at least a writeup that allows someone who
reads the list to understand how it works and to hand a
helping hand. I admit that for some things I'm just "out of
memory".
Still, all this does not hinder you to set up a better
documentation system or whatever. I've no problem with that.
But I think we need a working solution now and not a fancy
solution in the future. Yes, this is a "better ugly than
nothing" point of view.
Anyway, like with the tutorial: feel free to invent
something better, implement it and set it up. I'd gladly
hand it over. I really don't like to write docs.
--
Kind regards, / War is Peace.
| Freedom is Slavery.
Alexander Wagner | Ignorance is Strength.
|
| Theory : G. Orwell, "1984"
/ In practice: USA, since 2001
-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/
_______________________________________________
Scid-users mailing list
Scid-users@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/scid-users
