This is the mail archive of the cygwin@cygwin.com mailing list for the Cygwin project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]

Other documentation resources - new discussion?


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/


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]