Benoit St-Pierre wrote:
Hi!
>> 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.
The one does not exclude the other. Just use relative links
and not ressource available only while online.
> As I see it, the tutorial provides commented screenshots.
> If maintaining the two versions is too complicated,
I see only one version. Maybe we missunderstand each other?
>> 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.
I just had the accumulation of photos in mind.
> 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.
I admit that I do not get the point here as Scids help is
almost HTML. Some tags that could most likely be regexp
replaced. Point is, if I refer to an icon within the docs it
has to be named like the button within the app. So I've to
keep track of the internal naming.
> 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.
Hm, but this requires the reader to go over the whole thing.
To me this makes it imperative to get it very short and only
very simple tings can come up. I don't think many people
would read a 250 pages tutorial. - "Damn, is it that
complicated?!"
> (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.
Format it properly say indented in a smaller font, so you
can see easily that you can skip it or, if you don't know
if this is an interesting chapter yu read the abstract and
know whether or not without reading the 20 pages to follow.
I used that style in my recent thesis, I felt it is helpful
for the reader. (As did the reviewers.)
> If the reader need keywords for 3-4 paragraphs' lessons,
Ah. Here it is. ;) 3-4 paragraphs will indeed only scratch
some surface. I had a longer format in mind. Sorry.
> The tutorial is not the manual. The manual should provide Scid glossary.
I do not comply to this. What's the place the newbe is
intended to look up the basics? The tutorial. Then it should
also explain the necessary terms maybe a bit more so the
reader can understand the more complex parts.
>> 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.
I don't think so. If you talk about PGN and how to open it
and convert it to a base, e.g. This very part of the
tutorial should point the reader to the
- PGN definition in the tutorials glossary (what is that
beast?)
- help-page about opening a PGN
- help-page about creation of a DB
- help-page about importing a PGN
- help page about exporting a PGN
Especially if your tutorial is such a short format extensive
linking to the elaborated docs IMHO is imperative and should
definitely appear at the points where the reader stumbles
upon the terms.
Example from another area, say your tutorial says:
With cgoban you can edit an sgf file by selecting the
"Edit SGF File" from the main screen.
Up to you: what is SGF, why the hell do I want to edit it,
where do I get those things, and what for?
IMHO these infos have to be right in place. Ideally SGF-File
links to the glossary, telling you that it is the usual
format for the exchange of Go games, that you can get those
as results of your online games or form a lage database of
Go games online. It will tell you that you want to edit them
to add your own annotations and that you want to know how to
handle them if you want to exchange your games with a
friend. (I'd also suppose a link to the glossary for "goban"
and "cgoban" ;)
If the tutorial results in extensive use of <place your
favourite search engine here> to clearify this I think there
is room for improvment. If I also consider an offline format
all this info has to be contained within the tutorial in
some appendix.
--
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
[email protected]
https://lists.sourceforge.net/lists/listinfo/scid-users
