> I feel important that the tutorial as such is self-contained. IMHO one should
> be able to fetch a ZIP file with the tutorial, just unpack and read it
> offline. Say, while you're on the train or something the like.
Zipping the tutorial might be a good idea. But I would like it to be
part of Scid's site, with Scid's navigation. As I see it, the
tutorial provides commented screenshots. If maintaining the two
versions is too complicated, it could be condensed and put as the
Quick Guide of Scid Help.
> Versioning of images is Ok for me, probably it is more suitable to use some
> images/3.6.25/ subdir, ie. a subdir for
each version.
I doubt it, since you lose the information when the image is outside
the architecture. People capture screenshots, at least I do. This is
just for me anyway.
> Index is a keyword index, I guess. Your idea right now is to create a linear
> text? One that should be read from the
begining towards the end?
The index should contain all the indices we have the power to provide.
Giving that page at the end is effective : when someone just finished
the tutorial, he might want to jump to some part that interested him
the most. Yes, it is supposed to be read as linear lessons, like the
actual tutorial.
> Hm. I can imagine in a tutorial that it covers them as
well. In fact I think it even should, how should one learn
about them otherwise? Of course one should start writing the
basics first, but for an html-based document one could think
of the idea of a living document, ie. one that receives
permanent updates and extensions, resulting in the more
advanced topics to be added later on. Also consider more
than one author to balance workload and add expertise in
areas you do not use yourself extensively.
I disagree. The tutorial begins with launching the application ! We
should keep in mind who we are talking to : for now, we suppose that
the reader knows how to open the computer, find Scid's website, and
install Scid. For now, I think we could refer the other readers to
the help files. It is possible to create little documents for
specific readers, like **Scid of the Engine Maverick** or **Scid for
the Chess Historian**.
But the help files should be written as a manual. Another reason to
reverse the order of production : from html to tcl, not the other way
around.
> Looks good for a start. I'd probably split the latter in
+ studying chess
+ playing chess
Simply to get it a bit shorter and less complex. Also I feel
it important that each of these chapters is selfcontained,
if necessary, crosslinking to other parts in the tutorial.
(That's why I asked if you consider a linear or a hypertext
layout.)
The lessons won't be divided in chapters for now, so the division is
not structural, as I need to modify it as I write. There is still
some thinking to do, as I strongly believe in homogeneity. All the
tutorial shall be self-contained, but maybe not the chapters. (That
may be why chapters are not books, except bad ones, where you find
collections of articles.) That would be writing four or five separate
documents and providing meta-information ("in this chapter, you
will...") gets tedious, if the reader reads that every single page.
What will be provided is summaries, like the one at the beginning of
the page. If the tutorial gets too long, separating it into multiple
HOW TO's might be the best solution, I concede. I thought at first
that a single page would be enough, as I am impatient : it will take
some more writing to do before convincing myself that we need a series
of tutorials.
> I'd also add a short abstract to each chapter which
describes the main topics, and/or a list of keywords. I
consider that many users may have used e.g. ChessBase or
ChessAssistant or whatever and may have an idea. Those
people would like to skip some parts, but probably the wrong
one. E.g. I'd most likely skip the first one (things yo udo
with games) but depending on it's contents it's not wise to
do so. This should clearify in an abstract or list of
keywords.
If the reader need keywords for 3-4 paragraphs' lessons, then the
writer does not know how to select the titles in his page. We should
use the <dfn> tag to mark every keyword : that helps the creation of
the index and the updating of the <meta> keywords.
> This might be true, but at least "I have some strange files
called epd. What is that?" should be answered in the
tutorial or it's glossary. I think an extensive glossary
would be a good thing, I can imagine hyperlinking from the
text to the glossary.
The tutorial is not the manual. The manual should provide Scid glossary.
> Then guiding the user to the right topic there is surely
helpful. (See also ... in Scids online help.)
Yes, indeed. That shall be the main concern of the last section of
the last page.
-------------------------------------------------------------------------
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
[email protected]
https://lists.sourceforge.net/lists/listinfo/scid-users
