Other documentation resources - new discussion?

Other documentation resources - new discussion?

[Larry Hall (RFK Partners, Inc)]

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@rfk.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/

Re: Other documentation resources - new discussion?

[Bret Jordan]

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@rfk.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@coe.utah.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/

Re: Other documentation resources - new discussion?

[Enoch Wu]

Well, there is something in this mailing list that shares a common problem with
any mailing list or any newsgroup dealing with Unix. Some questions are Cygwin
specific and is a consequence of emulation. Some are Unix questions in 
general. Some are seemingly naive questions like why the bash shell is not 
GUI based (not the exact wording). People of all knowledge levels join this
group. I think we can focus on the most common problems. Once I saw a post
from an apparently experienced Unix user who tried to unpack files after the 
download by setup.exe. I don't know why something as obvious as this is 
missed when the instruction is literally on the front page of www.cygwin.com 
and right before one's eyes. Possibly someone never installed software on
Windows? The phrase "run setup.exe" automatically implies "click to install" 
to most Windows users except someone who has never installed a Windows software.

If the question arises from a bug that a new user encounters, it will really 
need to be handled on a case by case basis. How do you go about trying to
help them help themselves? 

If there is some aspect of Cygwin that will not change, then we could focus 
on documenting them like a piece of production.

Documentation is usually somewhat lagging the state of the codes in any 
ongoing projects involving free software. Programmers are more interested 
in coding than documenting and that's alright too because without these 
programmers there will be no free software. Most good programmers will
provide documentation instantly but only in the form of comments in the
source code. Generally this form of documentation would keep up with 
the code. These would generally be too involved with the inner details of
Cygwin and cannot be explained by anyone other than the programmer
themselves. On the other hand if it is a bug fix, then the fix is almost
transparent to the user -- it is not essential to know that it is fixed
unless a program relies on a bug being there, like Xemacs broken becuase 
Cygwin has improved.

Fortunately, there are people who are interested in documentation. That's good.
For some, writing documentation is not easy if they don't know the state of
the Cygwin project or that there is a temporary patch that is hard to explain
without wasting time. Some patches are better not revealed to the general
user.

We should write about the part of Cygwin that will not change and treat that
piece of documentation like a finished product without costly printing. 

Perhaps something like this will encourage users to print them and read them
like a well indexed manual. You know some people find it easier to read books
than HTML pages. For me, I sometimes use the plain text version of a manual
to be able to search through 1 MB of writing! If the manual is one big HTML
page, I can also do a quick search. PDF or POSTSCRIPT is terribly slow for 
searches.


EW

 
On Tue, Jul 03, 2001 at 06:17:38PM -0400, Larry Hall (RFK Partners, Inc) 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@rfk.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/
> 
> 

--
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/