Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]
Groups > linux.debian.user > #178670
| From | Martin Read <zen75502@zen.co.uk> |
|---|---|
| Newsgroups | linux.debian.user |
| Subject | Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") |
| Date | 2017-03-11 12:50 +0100 |
| Message-ID | <tjNH3-2cd-5@gated-at.bofh.it> (permalink) |
| References | (1 earlier) <sTV7b-6Di-7@gated-at.bofh.it> <sUmh4-8nR-11@gated-at.bofh.it> <sUo9b-15k-1@gated-at.bofh.it> <sUMXT-8jd-11@gated-at.bofh.it> <tjL2x-hd-3@gated-at.bofh.it> |
| Organization | linux.* mail to news gateway |
On 11/03/17 08:32, cbannister@slingshot.co.nz wrote: > Oh, come on! What you call good documentation means > writing for a user who has no clue about what the > program does. That kind of documentation is *really important*, because that's a big part of how people who don't know how to use the software learn to use it; not everyone has a learning style well suited to beating their head against the brick wall of "all the documentation assumes you already know exactly what you want to do and just need a refresher of what the relevant command-line options are". Unfortunately, many programmers (and even a fair slice of experienced documentation writers, both professional and volunteer) are utterly hopeless at writing that kind of documentation, even if they're good at writing reference documentation for people who already know how to use the software. Well-documented software has multiple kinds of documentation: external reference documentation for experienced users, tutorials and other introductory documentation for inexperienced users, internal reference documentation for developers wanting to modify the software, integration documentation for using the software as part of a system with other software, ... > Imagine a recipe written for a user who has no clue > about cooking ... I mean where do you start? You > HAVE to assume the reader has a certain level of > expertise. There are, in fact, cookbooks (and cookery programmes on television, etc.) aimed at people who have no clue about cooking (yes, sometimes even at the level of "this is how you bring a panful of water to the boil").
Back to linux.debian.user | Previous | Next — Previous in thread | Next in thread | Find similar | Unroll thread
Why? -- "A Modest Proposal" Richard Owlett <rowlett@cloud85.net> - 2016-11-16 15:20 +0100
Re: Why? -- "A Modest Proposal" Lisi Reisz <lisi.reisz@gmail.com> - 2016-11-16 16:00 +0100
Re: Why? -- "A Modest Proposal" Jonathan Dowland <jmtd@debian.org> - 2016-11-16 16:20 +0100
Re: Why? -- "A Modest Proposal" Lisi Reisz <lisi.reisz@gmail.com> - 2016-11-16 19:40 +0100
Re: Why? -- "A Modest Proposal" Jonathan Dowland <jmtd@debian.org> - 2016-11-17 13:20 +0100
Re: Why? -- "A Modest Proposal" Lisi Reisz <lisi.reisz@gmail.com> - 2016-11-17 15:30 +0100
Re: Why? -- "A Modest Proposal" Jonathan Dowland <jmtd@debian.org> - 2016-11-17 15:50 +0100
Re: Why? -- "A Modest Proposal" Richard Owlett <rowlett@cloud85.net> - 2016-11-17 15:50 +0100
Re: Why? -- "A Modest Proposal" Lisi Reisz <lisi.reisz@gmail.com> - 2016-11-17 17:40 +0100
Re: Why? -- "A Modest Proposal" Curt <curty@free.fr> - 2016-11-17 18:10 +0100
Re: Why? -- "A Modest Proposal" kamaraju kusumanchi <raju.mailinglists@gmail.com> - 2016-11-22 06:40 +0100
Re: Why? -- "A Modest Proposal" <tomas@tuxteam.de> - 2016-11-16 16:40 +0100
Re: Why? -- "A Modest Proposal" Richard Owlett <rowlett@cloud85.net> - 2016-11-17 16:00 +0100
Re: Why? -- "A Modest Proposal" "John L. Ries" <jries@salford-systems.com> - 2016-11-17 19:00 +0100
Re: Why? -- "A Modest Proposal" Greg Wooledge <wooledg@eeg.ccf.org> - 2016-11-17 22:40 +0100
Re: Why? -- "A Modest Proposal" <tomas@tuxteam.de> - 2016-11-17 22:40 +0100
Re: Why? -- "A Modest Proposal" rhkramer@gmail.com - 2016-11-18 00:10 +0100
Re: Why? -- "A Modest Proposal" <tomas@tuxteam.de> - 2016-11-17 22:30 +0100
Re: Why? -- "A Modest Proposal" Greg Wooledge <wooledg@eeg.ccf.org> - 2016-11-17 22:40 +0100
Re: Why? -- "A Modest Proposal" <tomas@tuxteam.de> - 2016-11-17 22:40 +0100
Re: Why? -- "A Modest Proposal" Greg Wooledge <wooledg@eeg.ccf.org> - 2016-11-17 23:00 +0100
Re: Why? -- "A Modest Proposal" Reco <recoverym4n@gmail.com> - 2016-11-18 09:20 +0100
Re: Why? -- "A Modest Proposal" rhkramer@gmail.com - 2016-11-18 00:10 +0100
Re: Why? -- "A Modest Proposal" emetib <chadbrabec@gmail.com> - 2016-11-18 09:50 +0100
Re: Why? -- "A Modest Proposal" <tomas@tuxteam.de> - 2016-11-18 10:40 +0100
Re: Why? -- "A Modest Proposal" "Thomas Schmitt" <scdbackup@gmx.net> - 2016-11-18 11:10 +0100
Re: Why? -- "A Modest Proposal" emetib <chadbrabec@gmail.com> - 2016-11-18 20:30 +0100
Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") cbannister@slingshot.co.nz - 2016-12-29 15:10 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Xen <list@xenhideout.nl> - 2016-12-29 19:10 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Xen <list@xenhideout.nl> - 2016-12-29 19:10 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Catherine Gramze <rhiamom@gmail.com> - 2016-12-29 19:40 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Xen <list@xenhideout.nl> - 2016-12-29 19:40 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Xen <list@xenhideout.nl> - 2016-12-29 19:40 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Catherine Gramze <rhiamom@gmail.com> - 2016-12-29 19:50 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Xen <list@xenhideout.nl> - 2016-12-30 02:40 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") rhkramer@gmail.com - 2016-12-30 03:30 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Lisi Reisz <lisi.reisz@gmail.com> - 2016-12-30 03:40 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Greg Wooledge <wooledg@eeg.ccf.org> - 2016-12-30 15:40 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Dan Purgert <dan@djph.net> - 2016-12-30 18:00 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Dan Purgert <dan@djph.net> - 2016-12-30 15:40 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") rhkramer@gmail.com - 2016-12-30 15:50 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") rhkramer@gmail.com - 2016-12-30 15:50 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Lisi Reisz <lisi.reisz@gmail.com> - 2016-12-30 16:00 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") John Hasler <jhasler@newsguy.com> - 2016-12-30 17:20 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Xen <list@xenhideout.nl> - 2016-12-31 08:30 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Xen <list@xenhideout.nl> - 2016-12-31 09:50 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Lisi Reisz <lisi.reisz@gmail.com> - 2016-12-31 10:40 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Catherine Gramze <rhiamom@gmail.com> - 2016-12-31 17:20 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Xen <list@xenhideout.nl> - 2017-01-01 13:00 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Xen <list@xenhideout.nl> - 2017-01-01 13:20 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Xen <list@xenhideout.nl> - 2017-01-01 14:00 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Nemeth Gyorgy <friczy@freemail.hu> - 2016-12-31 10:40 +0100
Re: Do have programs have poor documentation? "Thomas Schmitt" <scdbackup@gmx.net> - 2016-12-31 12:00 +0100
Re: Do have programs have poor documentation? Xen <list@xenhideout.nl> - 2017-01-01 12:40 +0100
Re: Do have programs have poor documentation? "Thomas Schmitt" <scdbackup@gmx.net> - 2017-01-01 14:10 +0100
Re: Do have programs have poor documentation? Xen <list@xenhideout.nl> - 2017-01-01 19:10 +0100
Re: Do have programs have poor documentation? "Thomas Schmitt" <scdbackup@gmx.net> - 2017-01-01 20:50 +0100
Re: Do have programs have poor documentation? Gene Heskett <gheskett@shentel.net> - 2017-01-01 15:10 +0100
Re: Do have programs have poor documentation? "Thomas Schmitt" <scdbackup@gmx.net> - 2017-01-01 20:50 +0100
Re: Do have programs have poor documentation? Gene Heskett <gheskett@shentel.net> - 2017-01-02 02:10 +0100
Re: Do have programs have poor documentation? Lisi Reisz <lisi.reisz@gmail.com> - 2017-01-02 02:30 +0100
Re: Do have programs have poor documentation? David Wright <deblis@lionunicorn.co.uk> - 2017-01-02 16:00 +0100
Re: Do have programs have poor documentation? rhkramer@gmail.com - 2017-01-02 17:30 +0100
Re: Do have programs have poor documentation? David Wright <deblis@lionunicorn.co.uk> - 2017-01-02 18:20 +0100
Re: Do have programs have poor documentation? rhkramer@gmail.com - 2017-01-02 18:50 +0100
Re: Do have programs have poor documentation? Eike Lantzsch <zp6cge@gmx.net> - 2017-01-01 18:00 +0100
Re: Do have programs have poor documentation? Xen <list@xenhideout.nl> - 2017-01-01 19:30 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") rhkramer@gmail.com - 2016-12-31 15:20 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Xen <list@xenhideout.nl> - 2017-01-01 12:40 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") David Wright <deblis@lionunicorn.co.uk> - 2017-01-02 15:50 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") rhkramer@gmail.com - 2017-01-02 17:20 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") David Wright <deblis@lionunicorn.co.uk> - 2017-01-02 18:10 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") rhkramer@gmail.com - 2017-01-02 18:50 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Jörg-Volker Peetz <jvpeetz@web.de> - 2017-01-02 19:10 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Xen <list@xenhideout.nl> - 2016-12-30 02:40 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Lisi Reisz <lisi.reisz@gmail.com> - 2016-12-30 03:30 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") deloptes <deloptes@gmail.com> - 2016-12-30 18:30 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Dan Purgert <dan@djph.net> - 2017-01-01 12:40 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Nicolas George <george@nsup.org> - 2017-01-01 12:50 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") deloptes <deloptes@gmail.com> - 2017-01-01 14:10 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Nicolas George <george@nsup.org> - 2017-01-01 15:10 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") deloptes <deloptes@gmail.com> - 2017-01-01 16:40 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Nicolas George <george@nsup.org> - 2017-01-01 17:20 +0100
[OT] on education [was]: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") deloptes <deloptes@gmail.com> - 2017-01-01 20:40 +0100
Re: [OT] on education [was]: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Nicolas George <george@nsup.org> - 2017-01-01 23:50 +0100
Re: [OT] on education [was]: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Joel Rees <joel.rees@gmail.com> - 2017-01-02 01:30 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Rob van der Putten <rob@sput.nl> - 2017-03-12 17:50 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Xen <list@xenhideout.nl> - 2016-12-31 08:30 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Lisi Reisz <lisi.reisz@gmail.com> - 2016-12-31 10:30 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Xen <list@xenhideout.nl> - 2017-01-01 13:00 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Lisi Reisz <lisi.reisz@gmail.com> - 2017-01-01 13:00 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Xen <list@xenhideout.nl> - 2017-01-01 13:30 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") deloptes <deloptes@gmail.com> - 2017-01-01 14:20 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Xen <list@xenhideout.nl> - 2017-01-01 18:00 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Xen <xen@dds.nl> - 2017-01-01 20:10 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Bob Holtzman <holtzm@cox.net> - 2017-01-02 20:40 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") cbannister@slingshot.co.nz - 2017-03-11 10:00 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Martin Read <zen75502@zen.co.uk> - 2017-03-11 12:50 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") deloptes <deloptes@gmail.com> - 2017-03-11 14:30 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Doug <dmcgarrett@optonline.net> - 2017-03-11 19:30 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Dan Purgert <dan@djph.net> - 2017-03-13 13:10 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Catherine Gramze <rhiamom@gmail.com> - 2016-12-30 04:40 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Xen <list@xenhideout.nl> - 2016-12-31 08:40 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Lisi Reisz <lisi.reisz@gmail.com> - 2016-12-30 12:40 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Richard Owlett <rowlett@cloud85.net> - 2016-12-30 13:30 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Dan Purgert <dan@djph.net> - 2016-12-30 15:50 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") rhkramer@gmail.com - 2016-12-30 15:50 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") deloptes <deloptes@gmail.com> - 2016-12-30 20:50 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Lisi Reisz <lisi.reisz@gmail.com> - 2016-12-31 00:20 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") deloptes <deloptes@gmail.com> - 2016-12-31 01:10 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Lisi Reisz <lisi.reisz@gmail.com> - 2016-12-31 01:50 +0100
[OT] Antikythera mechanism [was Re: Do have programs have poor documentation?] Miles Fidelman <mfidelman@meetinghouse.net> - 2016-12-31 03:20 +0100
Re: [OT] Antikythera mechanism [was Re: Do have programs have poor documentation?] deloptes <deloptes@gmail.com> - 2016-12-31 10:20 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Rob van der Putten <rob@sput.nl> - 2017-03-11 22:50 +0100
Re: Why? -- "A Modest Proposal" kamaraju kusumanchi <raju.mailinglists@gmail.com> - 2016-11-22 07:10 +0100
Re: Why? -- "A Modest Proposal" Darac Marjal <mailinglist@darac.org.uk> - 2016-11-22 13:00 +0100
Re: Why? -- "A Modest Proposal" Richard Owlett <rowlett@cloud85.net> - 2016-11-22 13:30 +0100
csiph-web