I agree with this:
On Tuesday, May 22, 2012 7:52:23 AM UTC-7, kcrisman wrote:
>
> I was introducing some folks to downloading Sage on Windows the other day,
> and I think that this particular workflow is proving to be confusing to
> more than just Mr. Rose.
I think it's very simple.
The information everyone is looking for is in the ReadMe file at the end of
a long list of redirecting links. This is the information that needs to be
prominently displayed on a web page. When you click, "download", the
download begins.
The technical details to make that happen are not the end-user's
responsibility.
There should be a page with *step-by-step instructions,* with screenshots.
Each step that is necessary for the installation, is necessary. The more
time consuming and unpleasant such documentation might seem to be. . .
well, the answer's in the question.
I use this guideline: Invariably, where I encounter the words, "then all
you do is {explanation}", whatever is in the brackets glosses over the
principal difficulty.
I am not happy about how frequently it obtains.
In a related matter, I suggest an
*{Experiment:}*
Pick a friend. Make sure this friend does not run his/her own Linux
installations or program for a living. This friend is 95+% of computer
users. Show this friend the link in the LaTeX and SAGE documentation which
says, "go to ctan.org and download it there".
This test is very simple. Are the directions "go to ctan.org and download
it there" sufficient?
That is, *are these in fact the steps, in order, which are sufficient to go
from zero to Latex?*
*
*
Does your friend even *find* the downloadable files at ctan.org?
If so, do they know which ones to get?
I think "insufficient" is a very kind thing to say, and perhaps even
dishonest. Nobody has any idea, really, how I'm supposed to install Latex.
So it's left up to me.
Oh good.
{/experiment}
I realize you have no idea what installation I want.
And that's the problem. The user doesn't either. Here is a simple and
obvious rule:
*Anyone following this link to a Latex installation is only doing so
because SAGE needs it.*
*
*
You already know this person doesn't know
-how to install Tex,
-what editor to use or even
-what criteria to adopt to evaluate the question
-how to make it known to SAGE.
-why any of this is necessary
You know they will have to learn about all of these things before they can
figure out *how to figure out* what installation to get, before they can
figure out how to install it, and get through the installation, before they
can make it known to SAGE...
before they can have math symbols, which is the reason they clicked on the
link.
This is not okay. It is easy to fix.
You make an arbitrary choice. You *pick* an editor, and a Tex
installation, and you make it part of SAGE, because SAGE can't display math
without it. It doesn't matter what you pick. What matters is that the *user
can see fonts, and edit documents.* We can fuss about the pros and cons of
a particular installation once there is one. This is a good conversation,
because it means SAGE is usable.
The current definitions of "usable" and "easy", "just", "interface" are not
okay.
In general, for anyone not already fully literate in the details, the
information the end user needs is systematically left out of the
instructions.
No product manual should ever
EVER
be a list of method-syntax followed by command-line examples.
The documentation doesn't acknowledge the difficulties. I think it's that
part of direction-giving when there are a whole bunch of steps that will
take forever to explain, and so we hand-wave and summarize the whole
process as a single block. "once you get {kit}, then you install
{kaboodle}, and voila" where kit and kaboodle are complex operations with
an arbitrary number of steps. Invariably [ ;-) ] "kit" requires you
first to install *shebang*, and *of course* there is an interpreter between
{kit} and {kaboodle}. But there are a dozen ways to do that, so the choice
is left up to the user.
We have the syntactic luxury of summarizing this into a single verb.
The end user does not.
Directions like this are not merely confusing, they are demonstrably
insufficient to answer the question. We *know it*. It would take so long
to explain each step, we instead make a list of assumptions about what we
expect the end-user to know how to do, and refer to them by summary. We
pass the responsibility along.
Which is the same thing as saying, not-giving-instructions.
There are times and places this is not okay, and I believe an open source
project designed to be accessible to everyone is such a place.
I think this is a problem with SAGE, in general. The special Lie Algebras
tools and documentation is really not very important. You know that,
right? The people that is written for can perfectly well handle
themselves, and the purchase of a $1000 mathematical program to assist them
is a serious question which does not necessarily imply an open source
answer.
Simple directions for installation, and a straightforward user interface;
those are much more important. Because most people won't justify such a
purchase, and shouldn't have to.
That is, if I am to believe the mission of the SAGE project.
The obstacles to installing SAGE and integrating it into a document, for
the average user, are arbitrary and largely undocumented.
*
*
> I wonder if there isn't some better way of putting very prominent
> instructions BEFORE the big list of mirrors, especially to point out that
> you'll want to know your arch. if you are on Mac or Linux and that there is
> a nice link for full instructions for the Windows version.
Please. Please. Please.
I know all of this is on the agenda, and takes time. But there are also
some development issues. Are you *certain* that you want the end-user to
have to choose his/her own Tex installation, in order to view and print any
mathematical symbols? It's not that I don't like Lie Algebras, and punch
their kids when you're not looking. It's that SAGE doesn't display math.
horse ------- cart -------->
ouf.
Likewise, I don't think the freedom to choose a Tex installation is useful.
As a stop-gap, sure. But not an answer. Put another way, the developers
of SAGE have not decided yet whether or not displaying mathematical symbols
is a part of the program. It's always a good idea to read our own
decisions back to ourselves, with different words. If the description is
accurate and it's not what we claim to be doing...
well.
The answer is again in the question.
Anyone who knows enough about Tex to think they need an improved, or
different installation package can replace the default one at his/her
leisure. There is no down side to this. Is there some licensing issue?
If so, can we *make* a font set and layout tools for SAGE?
My experience believing in open source but not wanting to inspect every
file on my computer -- and generally expecting to install things and have
them work-- is that documentation on websites like Sourceforge and other
independent, open-source projects operate in a seemingly willful ignorance
of the average computer user.
Right now SAGE is not a product for anyone who isn't comfortable with
command-line installations, hand-flagging compiler arguments to alter the
contents of VM messages, ignoring prominent warning messages from Windows
with the word "fatal" saying the steps are sufficient to aribtrarily damage
and destroy not only their installation but all data on their hard drive,
programming languages and scripting, etc.
If, by choice, SAGE were inaccessible to all but a *tiny* number of
computer users with a high degree of technical literacy in several fields,
I think you would all agree that is unacceptable. I will not make the case
that the two are the same. Anyone can learn anything. But every technical
obstacle you place *between* an end user not in that tiny pool, and using
the program in a straightforward way, is a *choice.*
Right now, SAGE is, *by choice*, arbitrarily difficult for the nontechnical
professional to install and use to perform ordinary algebraic and geometric
manipulations, or whatever else they may wish to do. Those arbitrary
difficulties include, but are not limited to, the entire field of computer
programming.
I believe those statements are a straightforward assessment of the facts at
hand.
I hope I do not sound strident or argumentative. This is something I have
thought about for a long time. Normally I shrug and walk away. I am not
interesting in giving up on SAGE. So I'm prepared to try to convince you,
and to help when I am able. I don't argue to be right or for the sake of
it. I am always willing to be convinced. I believe that making mathematics
accessible is an ethical and logical responsibility. I also find that the
principal technical obstacles to mathematical literacy are our own fault.
We construct them, and then fret about why no one understands. If we want
to be understood, that is easily enough done.
In any case, I'm here because I believe in SAGE. Hope that's clear.
Working on concision. promise.
--
To post to this group, send email to [email protected]
To unsubscribe from this group, send email to
[email protected]
For more options, visit this group at
http://groups.google.com/group/sage-support
URL: http://www.sagemath.org
