Re: Cygwin & openssh(d) & login without password

["lex ein" <lex_ein at f-m dot fm>]

On Tue, 5 Oct 2004 10:47:57 +0200, Corinna Vinschen  
<corinna-cygwin@cygwin.com> wrote:
> On Oct  5 16:00, David Campbell wrote:
> > I've read lots of web pages about how to set it up, and I believe I've
> > followed them, eg http://bumblebee.lcs.mit.edu/ssh2/ (for openssh to
> > openssh):
>
> WHY DON'T YOU READ THE OFFICIAL DOCUMENTATION INSTEAD? [caps mine]
> OpenSSH comes with a lot of man pages.  Then there's  
> /usr/share/doc/Cygwin/openssh.README.
> Then you could have used ssh-host-config and ssh-user-config for the
> basic configuration.

BECAUSE in the case of openssh(and others), the "official documentation"  
is of little use to a new user: information is not gathered, stored, or  
presented in a orderly, logical, or sensible hierarchical manner, is not  
meaningfully cross-referenced, and is not reasonably searchable.  There's  
just no usable thread to pull to unravel the mystery, either.

Let's examine the steps a new user might pursue:

1. A new user types 'help' and is presented with shell help.  Luckily,  
there's a mention of 'man -k'(which doesn't work) and 'info'.

2. The user might type 'help openssh' and be told to "try 'man -k openssh'  
which produces "openssh: nothing appropriate", a nice showstopper.  IF  
enterprising (and unafraid of the command line) enough, one _might_ try  
'man openssh', and 'info openssh' and be met with stony silence.

3. One may try 'help ssh' and be told to "try 'man -k ssh' which produces  
"ssh: nothing appropriate", another showstopper.  One _might_ ultimately  
try 'man ssh' instead and get (sort of) lucky.

4. 'man' and 'info' pages for ssh and sshd don't refer to  
/usr/share/doc/Cygwin/openssh.README, nor to  
/usr/share/doc/ssh/ssh-host-config or ssh-user-config.  So the new user is  
confronted with a brightly lit maze of lucidly defined options and  
configuration information.

5. A search using 'find / -name openssh*' does find appropriate  
directories, and even the README.  However, 'find' is ill-behaved: alone  
on a command line, it prints a _full recursive tree_ of the current  
directory. It's counterintuitive, and ill-documented.  'man find' shows no  
functional examples.  'find --help' lists options, not ordered by  
likelyhood of use, but _alphabetically_.  Only 'info find' shows a useful  
example.  And if the unlucky user forgets to type 'openssh*', they'll miss  
the README file.  Nice.

6. If a user has by some miracle heard of 'locate', a search using 'locate  
openssh' produces no results unless the user first runs 'updatedb'.

7. So someone in a hurry is likely instead to go out-of band:
  7a. Google for "cygwin openssh setup" produces NO useful official  
documentation in the first 50 results. In fact, the very first result is  
the http://tech.erdelynet.com/cygwin-sshd.html .  This resource has been  
maligned in this very cygwin list.
  7b. Windows Find "openssh" finds whatever _might_ be there to see.

8. Let's say the user somehow finds openssh.README.  Who the HELL decided  
to put the "If you are installing OpenSSH the first time" at the END of a  
four-page document?  Wading through panicky "important change" notices is  
rather pure torture, and irrelevant to the new user.

So these little unfindable jewels exist not to be used _by_ new users, but  
to be shot _at_ new users in ascerbic opprobrium.

To make the docs _easy_ to find would go against the dinosaur mentality of  
"Back in the day, I had to read all the docs before I could do anything,  
and now so do you."  The major difference being that back in the day, all  
the docs fit in a 1/4" booklet.  Now the task of forcing the user to  
imagine, compose a search for, search for, find, read, interpret, and  
correctly apply the hidden, terse, ultimately unhelpful, poorly referenced  
"official documentation" is simply onerous.

So, let's have no more asking new users why they didn't read the official  
documentation, then, eh?  They have _very good reasons_ for not doing so.


--
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple
Problem reports:       http://cygwin.com/problems.html
Documentation:         http://cygwin.com/docs.html
FAQ:                   http://cygwin.com/faq/