Documentation draft

[Neil Caldwell]

Hi all,

For those of you who don't know, I'm writing a user manual for Tagaini. I've just "finnished" drafting the third chapter (of 6 + 2 appendices currently.) I'm guess I'm going to have to put it somewhere for feedback eventually, which is really the whole point of writing to the list, so I'll try to do that sooner rather than latter. But in any case, I've documented Tagaini's search functionality and am about to move onto a chapter on settings. Should be back in a couple of days with more.

Neil

[Neil Caldwell]

Well, its Sunday afternoon and I've practically finished drafting the
manual itself, though I've added room for a chapter on trouble
shooting and two appendicies that have yet to be touched.

The document I have written is a reasonably lengthy user manual, So I
think it may also be an idea to update the current manual and use it
as a "quick start user guide," or some such. It is a lot more personal
than what I have written and so may be a better starting point for
some users.

I'm also wanting to write an advanced user reference or something for
those of us that don't really care about documentation because they
can work most of it out themselves. I'm thinking that a man page would
be good for this, but its not really compatible with windows systems.

I'm not going to attach what I've done so far to an email to a mail
group, but if anyone would like to lend a hand by proof reading /
picking apart what I've done then send me a reply and I'll send it on,
as I've not put it anywhere yet. I think Alex suggested I sign up to
gitorius so I may do that, though I may wait until I have gotten all
the images I'll want to include in order.

I do know a couple of people I think will be happy to edit it, so I
shouldn't be the only person editing it thank god. As my technical
documentation textbook put it so aptly, "We can never see our own
mistakes and we definitely cannot critique objectively our own work."

If people wouldn't mind I do have a few questions and requests; First
of all, does any one have any suggestions as to important things to
look at in a troubleshooting chapter? I plan to trawl the list and bug
tracker for issues that users may have, but if anyone thinks that
something may be important, then give us a yell.

A few questions about the program, for anyone who can answer:

* With the entry cache section on the general page in preferences,
What is default, 1000? And then does it keep n whole entries, for
use in the detailed view, or is it n entries remembered in the
results view, or both?

* The default font, is that a hidden program setting or a Qt/System setting?

* On the kanji entries settings page, in the additional information
section, What does
"Compounds" do? I've apparently got 30 of them being displayed an
entry, though I've not worked out what they are.

* Is it by design that, in reading practice, typing readings is not
kana sensitive or is it an offshot of getting kana insensitive search
recently?

* How do entries react in reading practice to readings from the
alternate readings section, instead of the main one. I seem to have
increased my study lists size by a stupid amount.

There are a couple of other inline questions, including these ones.
I'm sure I had some more, but hey, I forgot them whilst writing the
already very long email.

TL;DR: There will be new documentation. It is closer to being finished.

Neil

2009/12/11 Neil Caldwell <ncald...@gmail.com>

[Alexandre Courbot]

Neil really did an amazing work on the documentation. Tagaini really
needs a good user manual - not only from the user perspective, but
also because it will allow me to have a foreign look at the software,
which is needed in order to make it more user-friendly.

> The document I have written is a reasonably lengthy user manual, So I
> think it may also be an idea to update the current manual and use it
> as a "quick start user guide," or some such. It is a lot more personal
> than what I have written and so may be a better starting point for
> some users.

Indeed, a quick start would be nice - in that case, I should make it
shorter than the current manual.

> I'm also wanting to write an advanced user reference or something for
> those of us that don't really care about documentation because they
> can work most of it out themselves. I'm thinking that a man page would
> be good for this, but its not really compatible with windows systems.

That and no modern GUI software uses man pages anymore. I mean, I have
no manual entry on my system for firefox, konqueror or korganizer.
Topics in the help menu are much more adequate and intuitive for the
user IMHO.

> I'm not going to attach what I've done so far to an email to a mail
> group, but if anyone would like to lend a hand by proof reading /
> picking apart what I've done then send me a reply and I'll send it on,
> as I've not put it anywhere yet. I think Alex suggested I sign up to
> gitorius so I may do that, though I may wait until I have gotten all
> the images I'll want to include in order.

Don't hesitate to work on your own git branch - it's designed to host
work-in-progress, and anyway I can merge your work to the main branch
when you feel it's complete enough. Plus, that would allow you to keep
up-to-date with the latest developments.

> If people wouldn't mind I do have a few questions and requests; First
> of all, does any one have any suggestions as to important things to
> look at in a troubleshooting chapter? I plan to trawl the list and bug
> tracker for issues that users may have, but if anyone thinks that
> something may be important, then give us a yell.

I think your section about fonts and input methods covers most of the
trouble people may have.

> * With the entry cache section on the general page in preferences,
> What is default, 1000?   And then does it keep n whole entries, for
> use in the detailed view, or is it n entries  remembered in the
> results view, or both?

We are getting into the internals here. Simply put, Tagaini is just a
database on top of which I built a user interface. Entries are the
items that can be displayed in the results and detailed view and are
accessible through their type (either vocabulary or kanji) and a
unique identifier.

When you make a search, a SQL request is executed that returns a list
of (type, id) of the entries that match. The next step, in order to
display these entries, is to load them from the database, i.e. to get
their readings, parts of speech, stroke animations, ... and put them
into a structure the program can use. This takes some time, so this is
why there is this "cache" system that ensures that at least the
specified number of entries remain in memory even if they are not used
anymore. In case the next request returns the identifier of one of
these cached entries, it can be used directly without needing to
reload it from the database.

Just to say, this setting only has a small performance impact and it
is safe to leave it as it is. Only people who want to display
thousands or entries at the same time may want to increase it.

> * The default font, is that a hidden program setting or a Qt/System setting?

It's a system setting - the font that the system uses for all other programs.

> * On the kanji entries settings page, in the additional information
> section, What does
>  "Compounds" do? I've apparently got 30 of them being displayed an
> entry, though I've not worked out what they are.

They are the kanjis that uses the current kanji as a part of
themselves. For instance, 坂 is a compound of 反.

> * Is it by design that, in reading practice, typing readings is not
> kana sensitive or is it an offshot of getting kana insensitive search
> recently?

It's by design - the user is supposed to give a reading (i.e. how the
word sounds like), which is character-agnostic. HIraganas and
katakanas are pronunced the same - actually even a romaji answer
should be valid, if only I had written a romaji-to-kana converter.

> * How do entries react in reading practice to readings from the
> alternate readings section, instead of the main one. I seem to have
> increased my study lists size by a stupid amount.

Any valid reading is accepted.

I just noticed that you mentionned wildcards could be used as a prefix
in the Search bar section. While this will probably be true in the
near future, wildcards are only supported as suffixes as of today. But
since you reminded that point to me, this may change soon - so please
don't remove this part now. ;)

One last suggestion: the manual will be integrated into the software
once it is complete enough. In that case, the section about
installation is irrelevant, as the user will already have the software
installed on his machine. I suggest that this part to be into a
separate document, maybe an "installation instructions", that would be
accessible on the website. A lot of projects separate the usage and
installation documentations.

Anyway, this is a fantastic work, much better than what I would have
done myself (at least because of my limited English ability). Thanks a
lot for this huge contribution.
Alex.

[Neil Caldwell]

>> I'm also wanting to write an advanced user reference or something for
>> those of us that don't really care about documentation because they
>> can work most of it out themselves. I'm thinking that a man page would
>> be good for this, but its not really compatible with windows systems.
>
> That and no modern GUI software uses man pages anymore. I mean, I have
> no manual entry on my system for firefox, konqueror or korganizer.
> Topics in the help menu are much more adequate and intuitive for the
> user IMHO.
>

Ahh, a KDE user? I can't really argue with you about GUI software
having man pages because I don't use much of it, though wonder if it
is because KDE uses its own documentation system. I haven't used KDE
since version 2 so I'm not sure exactly what they do with all of that
stuff these days, though I seem to remember some KDE only standard
thing.

I actually use e16, and most everything I do in the terminal. Out of
the few programs with a GUI that I do use, Pidgin has one, GIMP has
one, Inkscape has one, gqview has one and I'm planning to move from
firefox to UZBL soon. Nothing else I use has a GUI, or at least one
that I use, which may be why I want to write a man page. That said,
GIMP and Inkscape also have a bunch of switches and use environment
variables, where Tagaini, I assume, only responds to the locale.

Perhaps I should consider doing one of those pretty reference sheets
as a png or svg....

>> * On the kanji entries settings page, in the additional information
>> section, What does
>>  "Compounds" do? I've apparently got 30 of them being displayed an
>> entry, though I've not worked out what they are.
>
> They are the kanjis that uses the current kanji as a part of
> themselves. For instance, 坂 is a compound of 反.

Ahh, so the opposite of components.

> One last suggestion: the manual will be integrated into the software
> once it is complete enough. In that case, the section about
> installation is irrelevant, as the user will already have the software
> installed on his machine. I suggest that this part to be into a
> separate document, maybe an "installation instructions", that would be
> accessible on the website. A lot of projects separate the usage and
> installation documentations.

KK. Like separating an INSTALL file from a README. I may also put the
IM stuff in a similar form in the trouble shooting section.

> Anyway, this is a fantastic work, much better than what I would have
> done myself (at least because of my limited English ability). Thanks a
> lot for this huge contribution.

Limited eh? I have to say the only thing I've really noticed about
your English is your use of the word "kanjis" as a plural for multiple
kanji. I honestly don't know if it should have a plural or not. I lean
towards "kanji" as both singular and plural, like sheep, because
Japanese doesn't have plurals in the same way English does. But then I
honestly don't know if I'm correct or not though.

There are a couple of things in the interface that I would have
written differently, but are not necessarily incorrect, just a
difference in dialects, So your written English at least is pretty
good.

Neil

[Alexandre Courbot]

> I actually use e16, and most everything I do in the terminal. Out of
> the few programs with a GUI that I do use, Pidgin has one, GIMP has
> one, Inkscape has one, gqview has one and I'm planning to move from
> firefox to UZBL soon. Nothing else I use has a GUI, or at least one
> that I use, which may be why I want to write a man page. That said,
> GIMP and Inkscape also have a bunch of switches and use environment
> variables, where Tagaini, I assume, only responds to the locale.

Exactly. If you look at GIMP or Inkscape's man pages, they explain the
command-line options and environment variables, not how to interact
with the GUI.

>> They are the kanjis that uses the current kanji as a part of
>> themselves. For instance, 坂 is a compound of 反.
>
> Ahh, so the opposite of components.

Put in better words, yes. ;)

> There are a couple of things in the interface that I would have
> written differently, but are not necessarily incorrect, just a
> difference in dialects, So your written English at least is pretty
> good.

Don't hesitate to make suggestions - I'm pretty aware that the UI is
far from being perfect.

Alex.

[Neil Caldwell]

I assume that EDIT is under a GPL or Creative Commons licence, or
equivalent, so I can just rip stuff (specifically the Part of Speach
list) out, reformat and include it, providing we provide some sort of
acknowledgement?

Neil

[Alexandre Courbot]

> Limited eh? I have to say the only thing I've really noticed about
> your English is your use of the word "kanjis" as a plural for multiple
> kanji. I honestly don't know if it should have a plural or not. I lean
> towards "kanji" as both singular and plural, like sheep, because
> Japanese doesn't have plurals in the same way English does. But then I
> honestly don't know if I'm correct or not though.

Forgot to answer that part. You are correct, the plural of kanji is
"kanji", without a "s". I have trouble getting rid of this bad habit.

There should not be any problem, especially if you put an
acknowledgement out of courtesy.

Alex.

[Neil Caldwell]

Just need to work out where I'm going to put that stuff to begin with.
Probably its own section at the end. Thanks.

Neil

2009/12/15 Alexandre Courbot <gnu...@gmail.com>: