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]

Re: Other documentation resources - new discussion?


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/


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