On 8 May 2011 16:51, Křištof Želechovski <[email protected]> wrote: > Dnia niedziela, 8 maja 2011 o 03:37:52 Duke Normandin napisał(a): >> >> Well what do you think that documentation is for - if not to teach. > > Note: > * Internet Explorer and Mozilla Firefox assume that you know what Web is > and what a Web browser is. > * Open Office assumes that you know the art of typesetting documents. > * GCC assumes that you know how to program in C. > > And so on. While this practice may be viewed as deplorable, it is a rather > common assumption. A book that you should read first is rarely included in > materials accompanying software because you are expected to learn what is in > the book before doing anything serious, and when you already have, you do not > need the book any more.
Hi Chris, Its perhaps a little harsh to call it deplorable, more an assumption of the audience for the document. > > Of course, there are positive examples also; I would mention the MIT X Window > System and Sun’s Java, both providing excellent introductory material. This > was, however, long ago. > Thats why documentation is often broken into tutorial - which does the introduction and hand holding user guide - which explains common use and idioms reference - data only, but precise and excruciating detail As you say above, after a while you don't need the tutorial and less of the user guide, just the reference. But even the tutorial will make assumptions about the audience having a certain level of knowledge and capabilities, documentation about a programming tool may operate on the basis that the reader knows how to program in some particular language/paradigm but knows nothing about the tool, and then readers without the requisite language/paradigm knowledge will struggle. But because they operate in an environment where "everyone knows" that background, the writers are unlikely to even think about explaining that background and may even struggle to do so because its so "self evident". See [1] and [2] for more on trying to explain a mental model of a complex software concept. And add to that programmers are often not motivated by documentation... Cheers Lex [1] http://byorgey.wordpress.com/2009/01/12/abstraction-intuition-and-the-monad-tutorial-fallacy/ [2] http://mvanier.livejournal.com/1205.html _______________________________________________ Geany mailing list [email protected] https://lists.uvena.de/cgi-bin/mailman/listinfo/geany
