Re: Thoughts on usability of tutorials [Was: Making eev use a "smaller full screen"]

[Eduardo Ochs]

On Tue, 20 Dec 2022, 09:01 Esteban Ordóñez, <quiliro@riseup.net> wrote:

Dear Eduardo:

I think that eev is a great software and that you are very prolific
worker.  But I have had several problems to follow your tutorials.
Perhaps it has been my laziness to read and analyze the way eev is
constructed or maybe it is my lack of enough intelligence required to
understand the workings of eev.  (I was going to write "workings of your
software" instead of "workings of eev".  But I feel that eev is mine
too!)

I have tryed several times to explain the problems that I have had.  You
have tryed to help me patiently and have put a lot of effort and love
into following up with my progress.  Thank you very much for what you
have contributed in my journey into eev (and of others which have asked
for help).  Nevertheless, I must say that you have dismissed my
situation and you have tryed to help me by solving my problem the way
that you would solve your problems.  But I need a little change in
strategy to understand better.  Please let me explain the process which
I think that I am going through when I am learning eev.  If you are not
willing to help me the way that I feel that would help me, I will not
blame you.  Rather, I feel that I am already a better person from the
encounters which I have had with you.

If you would go a little slower, it would help me a lot.  When you
explain, you go ahead and cover many things which are not my current
problem.  That makes me get lost about which are the steps I have to
take.  I do not have the criteria to know which of the informations that
you provide is the one to use at that moment.  So I get paralyzed and
just abandon.  (Of course that trying anything would be the right
course.  But it is not my normal reaction.)  I am very stubborn.  So I
come back motivated by my belief that eev uses the correct policy for
making machines: the most hackable construction, so that the user is not
a slave to the machine, but its master!

The current problem that I have could serve as an example.

El 2022-12-19 23:51, Eduardo Ochs escribió:

>   1. Run this to download or update the subtitles for a certain video:
>
>        (find-psne-eevvideo-links "2021-org-for-non-users" ".vtt")

When I evaluated this hyperlink, a new buffer popped up as I have been
accustomed to.  That is not complicated.  But that buffer contains a lot
of information.  There are two keybinding which I have learned that I
have to employ in these situations, F8 or M-e.  So when I use either of
these keybindings, something will happen.  I do not understand exactly
what happens.  (Lately I understand more.  But I do not follow the
direction that I need, it is just a flow.)  I have to do that because I
do not really know what to do.  Sometimes I have to kill some of those
buffers with M-k: when I either do not understand what has happened and
hope that the commands do what I needed to meet a precondition for what
I wanted (for example download a video into $S in order for it to be
played or a document in order for eev's versions of find-file to open
it) or when I have read all the document which is in the new buffer.  It
is not clear what is to be read for the current situation or which part
of the video is relevant and where to stop.

So my recommendation for the tutorials is to just mention the basics for
the issue at the time and have an area to go for more information.  The
fact that those two informations (specific and extense) are separate
would be very helpful to avoid getting lost in the beautiful jungle of
completeness.  If there is a video, have information of what to do in a
summary.  Then show all the information as optional additional
resources.  If there is a tutorial, mention a summary of what to do.
Then describe the steps in detail.  (I have seen this process in some
tutorial whare you have employed this process.)  If there is a question,
just mention the next step, not the whole process.  Be sure to ask what
is the current situation.  Then you can learn what to recommend.  It is
great to have the whole library of information.  But it is better for a
newbie that there is an obvious route to take as the first baby steps.
Later, the newbie will become an expert which will go directly to the
card catalogue, remember those?  :-D  I used to run away from those!
But I do think that they are useful when you know how they work.  (Yes,
I am that old.)

Hi!

You said (obs: sorry for the weird format, I am on a cell phone):

Then show all the information as optional additional

resources.  If there is a tutorial, mention a summary of what to do.

Then describe the steps in detail.  (I have seen this process in some

tutorial whare you have employed this process.)

Can you try to remember what was the tutorial in which I did things in a way that worked for you? I think that one of my main problems is that I don't know what are the questions that people have, and it's very hard to get them to ask these questions... so when I interact with people by IRC I can usually solve lots of people's problems in five minutes, but by e-mail, or by docs and tutorials, the same problems take five years to be solved...

Let me give an example. If a person asks "how do I change the default PDF viewer?" in many cases the real question is "how do I change the default PDF viewer in a way in which I can understand what has been done?"... and for some people a recipe using customize is the best way, for others a setq is best, and for others, like me, a setq preceded by two hyperlinks in comments that point to the docs and to the source code is best, because I am very good at noticing that the comments are pointers that can be ignored...

Some of the feedback that I receive on eev is from people who try to explain to me how they function, and they say things like: I am totally unable to skip over irrelevant information - every time that I read a page that has hyperlinks I read it linearly until I find the first hyperlink, then I follow that hyperlink, then I read that other page from the beginning until I find the first hyperlink, then I follow that hyperlink, and so on. Can you rewrite your documentation so that it will work for me? And I only know how to answer that in two ways: either with a "no" or as in one of the Zen koans about programming, in which, say, Master Sussman puts the sheet with the questions in the toaster, "and then the student was enlightened"...

Anyway, are you sure that what you asked above are your "real" questions? Because... well, let's imagine that you change them to the following. Let's imagine that you are on IRC, and you ask: "people, how do you read manpages and source code? How do you decide what to focus on and what to skip?"...

  Cheers,

    E.