-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA256 On 2015-09-02 22:15, Anton Aylward wrote:
On 09/02/2015 03:52 PM, Carlos E. R. wrote:
info pages, on the other hand, can be organized with a table of contents, with descriptive chapters and usage samples. It is up to the writer.
Documentation writing is generally acknowledged as being the hardest ting a programmer has to do, and many are simply not suited for it.
True.
Big name Firms such as IBM and Microsoft have professional writers who grill the programmers, write it up and have the programmers verify its correctness.
I remember the Borland Pascal and C manuals, organized in several books, and they were excellent. They even taught the language. The SuSE paper books were also excellent. I bought the DVD+CD install boxes, even if I could download them, only for having that book!
Sadly many of them don't always "debug" this by having a team of 'joe sixpack" inexperienced users try out the documentation and suggestions.
I recall at one small development shop I was vilified for suggesting have a naive user try the examples in the documentation before it was shipped. All the worse, because I'd tried them myself as an experienced user and they didn't work!
LOL. - -- Cheers / Saludos, Carlos E. R. (from 13.1 x86_64 "Bottle" (Minas Tirith)) -----BEGIN PGP SIGNATURE----- Version: GnuPG v2.0.22 (GNU/Linux) iF4EAREIAAYFAlXnW4wACgkQja8UbcUWM1whmwD/WHolWmKPAdl58ptUFThjW1aR Y1rd6obsikSHLo5hR+cA/izZFGb9HGvhKqPiL/fgVgFI4s/s3NNtdIxqb3El8qhP =G9uw -----END PGP SIGNATURE----- -- To unsubscribe, e-mail: opensuse+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse+owner@opensuse.org