Chris Wright <dhase...@gmail.com> writes: > 2013/5/12 Bryan Kilgallin > > What then is the purpose of documentation? I was trying to learn > this interface. But I found myself confounded by impenetrable > gobbledegook! > > That narrows it down, but it doesn't distinguish between sentence > structure and jargon.
Writing good documentation is harder than generally assumed. Fish wants to be "a user friendly commandline shell"; there are lots of different ideas that people associate with user friendly, ranging from "intuitive, usable without a manual" up to "powerful, flexible, lets me get the job done". An important question is: Who is this user documentation targeting? Should it be understandable for people completely new to the concept of shell? Should it cater to the experienced users that want to get accustomed to the "fish" way of doing things? There is a wide spectrum between "xy for dummies" and a concise, technical reference manual. It seems to me the fish user manual tries to find balanced middle ground, very much like e.g. the bash info manual. For example, when I tried to rephrase the paragraph in my last mail, I wasn't sure I quite knew what `token' actually meant. (If you search through the manual, you'll see the term is never explained.) This may be due to my lacking english skills, or a definition may be out of scope for this manual, because "everyone reading this should know that already" (which is a perfectly valid standpoint). Or finally it may simply be an oversight; if the writer uses that term all the time, he may think it is obvious to everyone. (BTW.: "My keyboard has no meta key" made my smile for exactly that reason). In that case, pointing it out is valid and valuable, no? (FWIW, I just checked: bash manual has a section 'Definitions' right after the Introduction which mentions and concisely explains `token'.) Well, anyways, fish is aiming at a new release, the first one for quite a while. Given a wide spread interpretation of "user friendly", there will be quite some users with little to no shell experience. Fixing "low hanging fruit", i.e. trying to catch the most difficult passages, would probably be beneficial cost/benefit wise IMHO. Well, if it makes it into the release and is shipped to all those computers that is. Having said all of that, I do agree however, that typos and upper/lower case issues should be best collected and send in one mail, contrary to the "one mail per issue" paradigm. [...] > Would examples help? They won't be as precise as the technical > explanation, but on the other hand, they would be more readily > apprehended by people who don't write compilers in their spare time. They most definitely do. Sure, won't be as precise, but that is not necessarily what they are there for: They supplement the explanation, probably point out some common use cases. If one can come up with good examples, they may be beneficial even for intermediate users. Perhaps, this is all obvious rambling, and being new to this list, to fish and all, I will shut up now :). FWIW, IMHO, ETC Memnon ------------------------------------------------------------------------------ Learn Graph Databases - Download FREE O'Reilly Book "Graph Databases" is the definitive new guide to graph databases and their applications. This 200-page book is written by three acclaimed leaders in the field. The early access version is available now. Download your free book today! http://p.sf.net/sfu/neotech_d2d_may _______________________________________________ Fish-users mailing list Fish-users@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/fish-users
