Mailing-List: contact cygwin-help AT sourceware DOT cygnus DOT com; run by ezmlm
Sender: cygwin-owner AT sources DOT redhat DOT com
Message-Id: <5.0.2.1.0.20010703170018.021ede70@imap.coe.utah.edu>
Date: Tue, 03 Jul 2001 17:13:30 -0600
To: cygwin AT cygwin DOT com
From: Bret Jordan <jordan AT coe DOT utah DOT edu>
Subject: Re: Other documentation resources - new discussion?
In-Reply-To: <4.3.1.2.20010703162823.0164e058@pop.ma.ultranet.com>
Mime-Version: 1.0
Content-Type: text/plain; charset="us-ascii"; format=flowed

When looking at this, I think one should be careful to not assume that 
people understand the lingo/terminology of working with a Unix type 
OS.  When all is said and done I believe this is really problem.  This is 
the problem with most documentation/books.  They are written by people that 
really understand the product but fail to remember what it was like when 
they were first learning it.

The basic documentation should be filled with information that people that 
are new to cygwin ask.

I would like to see the following:
1) a basic documentation (not wordy or bogged down) that targets the user 
that does not now what a mount point is
2) a detailed documentation for advanced users that gives dependencies and 
requirements for specific utiliites..

Examples:  We see lots of posts about getting SSHD to work.  Most of them 
are from new users that don't understand anything about Unix and have no 
idea to why the directory structure is the way it is or some other 
reason.  Then on the other hand you have users that are trying to do some 
thing unique with SSHD to get it to work in their environment (like use it 
in a different directory structure, or automate an sshd connection using 
RSA keys, or something weird).  It would be nice if the documentation was 
basic enough for the beginner and then had a section of detailed 
dependencies and knowledge for the advanced user.  (ex: your passwd file 
must be in /etc unless you recompile sshd, things that are common knowledge 
for people familiar with Unix, but totally foreign for us windows geeks.)

Just my 2 cents

Bret


At 06:17 PM 7/3/2001 -0400, you wrote:
>After some private email discussion with Warren Young, I'd like to open
>up discussion on the issue of Cygwin documentation.  Specifically,
>the goal here is to figure out how to provide users with more encompassing
>resources for solving their problems.  Currently, Cygwin has an FAQ which
>answers all sorts of questions about Cygwin, assuming they come up with
>some regularity.  However, it seems to me that there is a class of
>problems for which information is not easy enough or isn't available for
>users to find.  These areas have to do with getting Cygwin to work or even
>how to find any existing answers to issues.  Much of the information I'm
>referring to is in the email archives.  Some may not be.  Either way, I
>don't view this information as FAQs per-se but its still information that
>some users would find useful.  I categorize this area of documentation
>as a "Troubleshooting Guide", since it would seek to address a variety of
>specific issues that folks have when working with Cygwin.  The kinds of
>things that would go into a document of this type could be fairly broad.
>As such, organization of the information would be key.  Whether the
>information in the document is a copy of previous posts, simple search
>URLs to find the original in the email archives, information not mentioned
>anywhere else, or a combination of all of these is open to discussion.
>However, the goal would be to provide a resource for those who are looking
>for some information which doesn't meet the FAQ threshold (obviously, if
>something in this document did reach that threshold at a later date, the
>FAQ could just add an entry pointing to the "Troubleshooting Guide"
>topic).  Something like this would help bridge the gap between the FAQ and
>the email archives.  While the FAQ is easily navigated, due to its clear
>index of questions and the obvious hyper-linking, there's a valid concern
>that filling it with too much stuff that's not frequently-asked will tend
>to overwhelm some of those its meant to help, diminishing its value.  On
>the alternate end, the email archives are full of great information that
>covers lots of things not in the FAQ.  By its very nature though, it
>doesn't have an organized index and sometimes searching it for a topic
>of interest may not reveal important information on that topic.  The
>"Troubleshooting Guide" could help fill this void.  So, to me, the
>topics to consider are:
>
>    Do we need this?
>
>    What should it be (should its charter be limited to a specific area,
>                       like troubleshooting usage issues in Cygwin, or
>                       should it contain any information of "importance",
>                       like "Is XXXX ported yet?")
>
>    Where should it go (i.e. is there a strong reason to make it a part of
>                        the FAQ or other existing document rather than its
>                        own)?
>
>    What should we call it (I've referred to it above as the
>                            "Troubleshooting Guide" but I'm sure there's a
>                            better way to refer to this)?
>
>    If we need it, who wants to create/maintain it?
>
>The last question is key.  Its almost more important than the discussion
>itself! ;-)  Still, I expect that this is a bit of a chicken-and-egg
>thing.  The discussion may spur people's interest in working on such a
>task.  But the discussion is of limited value if the consensus is that
>this document is needed but nobody is interested in making it happen.  In
>that light, I'd request that we keep the discussion focused on the basics,
>so that we can reach a consensus on whether this is worthwhile or not
>relatively quickly.  Assuming the decision is that this is a worthwhile
>task and resource volunteer for this, there will be plenty of time
>afterward to add and tweak what's created.  It's usually easier to make
>lots of constructive detailed points based on something concrete than it
>is to do so with just a general concept.
>
>Those interested in working on this should follow-up to the list too, so
>other's are aware of your intent.
>
>Thanks for your attention.  OK, any debate? ;-)
>
>Larry Hall                              lhall AT rfk DOT com
>RFK Partners, Inc.                      http://www.rfk.com
>118 Washington Street                   (508) 893-9779 - RFK Office
>Holliston, MA 01746                     (508) 893-9889 - FAX
>
>
>--
>Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple
>Bug reporting:         http://cygwin.com/bugs.html
>Documentation:         http://cygwin.com/docs.html
>FAQ:                   http://cygwin.com/faq/


~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Bret Jordan                       Dean's Office
LAN Manager              College of Engineering
801.585.3765                 University of Utah
              jordan AT coe DOT utah DOT edu
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


--
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple
Bug reporting:         http://cygwin.com/bugs.html
Documentation:         http://cygwin.com/docs.html
FAQ:                   http://cygwin.com/faq/