New Browsers for Old

[Craig White]

On Thu, 2005-02-24 at 13:01 -0600, STYMA, ROBERT E (ROBERT) wrote:
> > 
> > For example, there are at least 1000 pages (dead tree form) of top
> > quality documentation at samba.org site and people ask basic questions
> > of initial setup of samba. Volunteers respond to questions 
> > and it takes
> > 1 - 3 days just to get a windows computer connected to a 
> > samba computer.
> > Seems to be a case where the homework would save everybody time and
> > trouble - I point them to the docs. Much more significant 
> > than answering
> > the question.
> > 
> > Craig
> 
> I think this is part of the problem.  "There are at least 1000 pages."
> To a new user, who is trying to determine what is the best way to accomplish
> something, looking through 1000 pages of documentation to find that this is
> or is not the best tool to accomplish what they have in mind somewhat
> discouraging.  Someone who wants to look at windows files across the network
> as opposed to someone who wants to share Linux files to windows needs a 
> different cross section of those 1000 pages.  The guy who wants to look at
> the windows on a partition on the hard drive of the Linux machine has to do
> something still different.  He could go through the whole 1000 pages only
> to find he was barking up the wrong tree.  
> 
> I think pointing a person to useful documentation and sometimes a bit
> of background is useful.  To continue the example, I am aware that
> the name Samba was derived from SMB which is sometimes called CIFS.
> When glancing through package titles looking for something, barring prior
> knowlege, the name Samba does jump out at me as having to do with
> Windows file systems.  Gimp is a slang term for a guy with a bad leg.
> It is a great image editor, but that is not obvious from the name.
----
Ignoring all the extraneous issues you have raised for a sec...

Assuming that someone has to read all 1000 pages to get their answers is
a mistake - I give people credit for being able to use a table of
contents, an index and/or search to find the specific things that they
are looking for.

Also - and I think most importantly - asking a question like on this
list or even on the samba list is asking someone to give you the
briefest cliff not version of the big book - I guess we have to decide
which is best but I always read the book because the cliff note version
often didn't help me on the tests and clearly gave me absolutely no
flavor for the author's style, intentions or tone.

In the case of samba - these guides are to quote the author, John
Terpstra as 'green' - always changing, always updating and very much
authoritative. They are clearly the best of breed when it comes to
documentation of open source software. I feel that narrow view answers
to questions by confused 'new users' tend to cheat the new users of the
rich resources available and even more so - the incredible philosophical
visions by the samba team hinted at in the 'HOWTO' and specifically
detailed in the 'BY EXAMPLE' books/documents.

Now - SMB / samba refers to 'Server Messaging Block' - Microsoft
terminology  CIFS - Common Internet File System are actually 2
distinctly different things and you can search the origin of the
meanings of them should you wish.

GIMP - like many other technology labels is an acronym for 'Graphic
Image Manipulation Program' - seems simple enough. Granted, a technology
dictionary can break these down for people. What is in a name? Seems to
me that the question has been asked a few times before.

Craig