Here is why I stopped working on help.tcl :
Almost all pages are too long. Topics need tightening. Information
suffers from being outdated.
Correcting errors is very tough. The tcl file with pseudo-html brings
no joy to the eyes. Having to join the programming cycle is
cumbersome. More importantly, there are lots of spaghetti writing
there.
Let's take a simple example : the About page, or the colophon. This
is referred as
<a Author>Contact information</a>
Here is the code :
set helpTitle(Author) "Contact information"
set helpText(Author) {<h1>Contact Information</h1>
<p>
The Scid web page is located at: <br>
<b><url http://scid.sourceforge.net/>http://scid.sourceforge.net/</url></b>
</p>
<p>
It has downloads of the latest version of Scid and any extra
files that are available.
</p>
<p>
Please send any comments, questions, suggestions or bug reports to
Pascal Georges
<b>[EMAIL PROTECTED]</b>
</p>
<h3><name Related>Related Links</name></h3>
<p>
If you enjoy using Scid, you may find the following websites interesting:
</p>
<ul>
<li><url http://scid.sourceforge.net/>http://scid.sourceforge.net</url>--
The program upon which Scid is heavily based. Scid was written by
Shane Hudson, with help from others.</li>
<li><url
http://www.tim-mann.org/chess.html>http://www.tim_mann.org/chess.html</url>
--
Home page of Tim Mann's <b>xboard & winboard</b> program which is a PGN
reader and an interface for Internet chess servers. His site also has
good information on Crafty, GNUchess and other free chess programs.</li>
<li><url
ftp://ftp.cis.uab.edu/pub/hyatt/>ftp://ftp.cis.uab.edu/pub/hyatt/</url>
--
the strong chess-playing program Crafty.
The subdirectory there named <b>TB</b> has many Nalimov-format tablebase
files that you can use in several chess programs and in Scid.</li>
<li><url
http://www.chesscenter.com/twic/>http://www.chesscenter.com/twic/</url>
--
TWIC (the week in chess), an excellent weekly bulletin of international
chess games in available in PGN format.</li>
<li><url
http://scid.sourceforge.net/doc/standard.txt>http://scid.sourceforge.net/doc/standard.txt</url>
--
the <b>PGN Standard</b>, created by Steven J. Edwards in 1994.
This text file explains the PGN and EPD formats in detail.</li>
</ul>
<p><footer>(Updated: Scid 3.6.2, December 2006)</footer></p>
}
Here are some parts that refers to this page :
> See the <a Author>contact information</a> page if you need to contact the
> author of Scid. [295-296]
> If you think of a useful hint to add to this page, please send it to the <a
> Author>author of Scid</a>. [313-314]
> <a Author Related>PGN standard</a> [1137]
> The spellcheck file "spelling.ssp" that comes with Scid does not contain the
> Elo rating information needed for this function, but a larger version of it
> called "ratings.ssp" is available from the <a Author>Scid website</a>.
> [2209-2211]
So this is not the About page, nor the colophon. This is simply a
list of references. There is no reason to provide Internet references
in a Help file : if the user has access to the Internet, he can access
to Scid's website. Only managing a page of external references would
be quite easier to maintain.
*****
Here is what should look like :
<h2>Scid<h2>
<p>Scid stands for <b>Shane's Chess Information Database</b>. Scid's
internals is built with C++ ; its graphical user interface is built
with Tcl/Tk. Scid is licensed is Free Software.</p/>
## We could plug here what means to be free. But I don't know what to say yet.
<h2>Original Author</h2>
<p>Scid has started in 1999, between the ears of one person named
<b>Shane Hudson</b>. Allegedly, he lives in Christchurch, New Zealand
with his wife Becky, his son Andrew, his daughter Ashley and two cats.
Some suspect that he transcended time, while others believe that he's
reverse engineering the universe to make it a better place. </p>
<h2>Actual lead programmer</h2>
<p>Since 2006, <b>Pascal Georges</b> maintains the project. Please
send all congratulations to him directly :
<b>[EMAIL PROTECTED]</b>. Please send any comment, question,
wish or bug report to <url
http://scid.sourceforge.net/feedback.html#mailing-list> Scid's Mailing
List</url>.
## We could also supress Pascal email if he prefers.
## This feedback.html page does not exist yet. It should exist soon enough.
## SML is a nice abreviation : sounds like smile.
<h2>Contributors</h2>
## We should aknowledge others work : there is a txt page on the site.
What to do ?
## Either we fit all names in a paragraph, or else point to a
contributors.html page.
Like any open projects, Scid requires its community to contribute.
You sure can contribute something. For ideas, check out <url
http://scid.sourceforge.net/contribute.html></url>.</p>
## This could be a different page than the mailing list, since we have
lots of project to market here.
## Coding, Centriscid, translations, donation?, etc.
<p><footer>(Updated: 2008-10-11)</footer></p> }
*****
That should be enough to get two points across to reduce the
maitenance effort. First, help.tcl should be reduced, not augmented.
That does not mean eliminating pages. On the contrary, in fact.
Second, we should minimize secondary references. The indices and the
Table of Contents must stay the main navigation tool, at least as long
as we don't have a team of documentalists. More importantly, all
information that requires the Internet to be useful should stay on the
Internet.
And now I have come full circle. And so I leave you to these thoughts
while I go finish the tutorial's pages for this week. They should be
available tomorrow, if all goes well.
Bye,
Benoit
-------------------------------------------------------------------------
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
