public inbox for docbook-tools-discuss@sourceware.org
 help / color / mirror / Atom feed
From: "Eric S. Raymond" <esr@thyrsus.com>
To: "Edward C. Bailey" <ed@redhat.com>
Cc: docbook-tools-discuss@sourceware.cygnus.com
Subject: Re: I'm trying to set up docbook-tools...
Date: Wed, 27 Dec 2000 06:36:00 -0000	[thread overview]
Message-ID: <20000706195444.D27191@thyrsus.com> (raw)
In-Reply-To: <lf7lay7tc4.fsf@pigdog.meridian.redhat.com>

Edward C. Bailey <ed@redhat.com>:
>                               So it's time to move on, and leave the
> Cult of the Sacred Tag mentality behind us now... :-)

Indeed.  And an important point: I wouldn't be so exercised about the
Cult of the Sacred Tag if, on some level, I didn't grok that the SGML
people have some reason behind the religion.  If it was all just just
bullshit, I could ignore it and go away.  As it is, the fact that the
power of these techniques is surrounded by a near-impenetrable thicket
of theology and jargon is deeply frustrating to me -- and the apparent
inability of SGML people to see that this is an issue is maddening!

> esr> Is it just me?  Am I crazy to think there's something wrong with a
> esr> 600-page tome on document production tools that *never once tells you
> esr> how to format a document?*
> 
> To be honest, and at least in the case of _DocBook: The Definitive Guide_,
> I think it's just you. [...]  To have this particular reference guide get
> into how the markup language is processed by one particular application on
> a subset of the possible platforms would be something similar to HP
> including a chapter called "Using Your New Printer to Print Romance Novels"
> in every LaserJet owner's manual. :-)

No, I'd say it's more like supplying schematics and chip masks for the 
printer's electronics and neglecting to document the front-panel controls.

Really.  What would it have cost to supply *one* explicit example of 
a document-production flow on Unix and Windows?  A few pages could have
made a huge difference -- in helpful symbolism, even if it couldn't
cover all the substance.

As it is, one is left with the impression that Mr. Walsh was so caught
up in the arcana of Scheme and CSS and DTD composition that he couldn't be 
bothered to descend to the level of actually showing the reader how to
actually use any of it.

(All right, everybody.  Calm down -- I'm not claiming that was his actual
state of mind, simply that that is the message the book sends.)

>     o If you were to change a few of the terms in ESR's comments, you'd
>       have almost exactly the same kinds of feedback we at Red Hat get from
>       users regarding the state of Linux documentation today.  So those of
>       us that do documentation for one or more open source software
>       projects should keep in mind that we ain't done yet -- not by a long
>       shot.  This complaint is true for DocBook documentation, and it's
>       true for many (most? all?) open source software projects.

Yup.  That's why I maintain, at last count, eight (8) different technical
FAQ documents.  
 
>                                                The important point
>       here is that we need to get away from the mentality that
>       introductory/tutorial texts are for clueless newbies, that hard-core
>       reference material is the only truly important documentation.  The
>       introductory stuff makes the technology accessible to people that
>       would otherwise not have access.

Amen.  Squared...
-- 
		<a href=" http://www.tuxedo.org/~esr ">Eric S. Raymond</a>

"Rightful liberty is unobstructed action, according to our will, within limits
drawn around us by the equal rights of others."
	-- Thomas Jefferson

WARNING: multiple messages have this Message-ID
From: "Eric S. Raymond" <esr@thyrsus.com>
To: "Edward C. Bailey" <ed@redhat.com>
Cc: docbook-tools-discuss@sourceware.cygnus.com
Subject: Re: I'm trying to set up docbook-tools...
Date: Thu, 06 Jul 2000 16:46:00 -0000	[thread overview]
Message-ID: <20000706195444.D27191@thyrsus.com> (raw)
Message-ID: <20000706164600.sdvDb7uMULvjfHXLnhkbb9lYACfEXIHQrV-rSKnvpGQ@z> (raw)
In-Reply-To: <lf7lay7tc4.fsf@pigdog.meridian.redhat.com>

Edward C. Bailey <ed@redhat.com>:
>                               So it's time to move on, and leave the
> Cult of the Sacred Tag mentality behind us now... :-)

Indeed.  And an important point: I wouldn't be so exercised about the
Cult of the Sacred Tag if, on some level, I didn't grok that the SGML
people have some reason behind the religion.  If it was all just just
bullshit, I could ignore it and go away.  As it is, the fact that the
power of these techniques is surrounded by a near-impenetrable thicket
of theology and jargon is deeply frustrating to me -- and the apparent
inability of SGML people to see that this is an issue is maddening!

> esr> Is it just me?  Am I crazy to think there's something wrong with a
> esr> 600-page tome on document production tools that *never once tells you
> esr> how to format a document?*
> 
> To be honest, and at least in the case of _DocBook: The Definitive Guide_,
> I think it's just you. [...]  To have this particular reference guide get
> into how the markup language is processed by one particular application on
> a subset of the possible platforms would be something similar to HP
> including a chapter called "Using Your New Printer to Print Romance Novels"
> in every LaserJet owner's manual. :-)

No, I'd say it's more like supplying schematics and chip masks for the 
printer's electronics and neglecting to document the front-panel controls.

Really.  What would it have cost to supply *one* explicit example of 
a document-production flow on Unix and Windows?  A few pages could have
made a huge difference -- in helpful symbolism, even if it couldn't
cover all the substance.

As it is, one is left with the impression that Mr. Walsh was so caught
up in the arcana of Scheme and CSS and DTD composition that he couldn't be 
bothered to descend to the level of actually showing the reader how to
actually use any of it.

(All right, everybody.  Calm down -- I'm not claiming that was his actual
state of mind, simply that that is the message the book sends.)

>     o If you were to change a few of the terms in ESR's comments, you'd
>       have almost exactly the same kinds of feedback we at Red Hat get from
>       users regarding the state of Linux documentation today.  So those of
>       us that do documentation for one or more open source software
>       projects should keep in mind that we ain't done yet -- not by a long
>       shot.  This complaint is true for DocBook documentation, and it's
>       true for many (most? all?) open source software projects.

Yup.  That's why I maintain, at last count, eight (8) different technical
FAQ documents.  
 
>                                                The important point
>       here is that we need to get away from the mentality that
>       introductory/tutorial texts are for clueless newbies, that hard-core
>       reference material is the only truly important documentation.  The
>       introductory stuff makes the technology accessible to people that
>       would otherwise not have access.

Amen.  Squared...
-- 
		<a href=" http://www.tuxedo.org/~esr ">Eric S. Raymond</a>

"Rightful liberty is unobstructed action, according to our will, within limits
drawn around us by the equal rights of others."
	-- Thomas Jefferson

  parent reply	other threads:[~2000-12-27  6:36 UTC|newest]

Thread overview: 116+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2000-12-27  6:36 Eric S. Raymond
2000-07-04  8:02 ` Eric S. Raymond
2000-12-27  6:36 ` Eric Lee Green
2000-07-04 10:25   ` Eric Lee Green
2000-12-27  6:36   ` madhu
2000-07-04 22:01     ` madhu
2000-12-27  6:36     ` Eric Lee Green
2000-12-27  6:36       ` Norman Walsh
2000-12-27  6:36       ` Sam Roberts
2000-07-05  7:40         ` Sam Roberts
2000-12-27  6:36         ` Ismael Olea
2000-07-05  9:57           ` Ismael Olea
2000-12-27  6:36           ` Mark Galassi
2000-07-05  9:59             ` Mark Galassi
2000-12-27  6:36     ` Sam Roberts
2000-07-05  7:32       ` Sam Roberts
2000-12-27  6:36   ` Mark Galassi
2000-07-04 11:21     ` Mark Galassi
2000-12-27  6:36     ` Norman Walsh
2000-07-07  7:49       ` Norman Walsh
2000-12-27  6:36   ` David C. Mason
2000-07-05  7:41     ` David C. Mason
2000-12-27  6:36   ` Norman Walsh
2000-07-06  9:21     ` Norman Walsh
     [not found]     ` <ndw@nwalsh.com>
2000-12-27  6:36       ` richard offer
2000-12-27  6:36         ` Norman Walsh
2000-07-07  7:49           ` Norman Walsh
2000-12-27  6:36         ` Eric Bischoff
2000-12-27  6:36           ` Norman Walsh
2000-07-28 10:44             ` Norman Walsh
2000-12-27  6:36     ` Chuck Dale
2000-12-27  6:36     ` docbook-tools-discuss: " Bill Campbell
2000-12-27  6:36       ` Norman Walsh
2000-12-27  6:36         ` Bill Campbell
2000-12-27  6:36         ` Edward C. Bailey
2000-12-27  6:36         ` Eric S. Raymond
2000-12-27  6:36     ` Eric S. Raymond
2000-12-27  6:36       ` Mark Galassi
2000-07-06 10:25         ` Mark Galassi
2000-12-27  6:36         ` Eric S. Raymond
2000-07-06 10:37           ` Eric S. Raymond
2000-12-27  6:36           ` Kendall Clark
2000-07-06 10:48             ` Kendall Clark
2000-12-27  6:36             ` Mark Galassi
2000-07-06 10:53               ` Mark Galassi
2000-12-27  6:36               ` Eric Lee Green
2000-07-06 13:38                 ` Eric Lee Green
2000-12-27  6:36                 ` Norman Walsh
2000-12-27  6:36       ` David C. Mason
2000-12-27  6:36         ` Eric Lee Green
2000-07-06 14:22           ` Eric Lee Green
2000-12-27  6:36         ` Eric S. Raymond
2000-07-06 11:59           ` Eric S. Raymond
2000-12-27  6:36           ` David C. Mason
2000-07-06 13:55             ` David C. Mason
2000-12-27  6:36             ` Eric Lee Green
2000-07-06 14:32               ` Eric Lee Green
2000-12-27  6:36             ` Eric S. Raymond
2000-07-06 14:52               ` Eric S. Raymond
2000-12-27  6:36               ` David C. Mason
2000-07-06 15:23                 ` David C. Mason
2000-12-27  6:36                 ` Eric S. Raymond
2000-07-06 15:52                   ` Eric S. Raymond
2000-12-27  6:36                 ` Eric Lee Green
2000-07-06 15:57                   ` Eric Lee Green
2000-12-27  6:36               ` Edward C. Bailey
2000-07-06 16:05                 ` Edward C. Bailey
2000-12-27  6:36                 ` Eric S. Raymond [this message]
2000-07-06 16:46                   ` Eric S. Raymond
2000-12-27  6:36                   ` Norman Walsh
2000-07-07  7:49                     ` Norman Walsh
2000-12-27  6:36                     ` Eric S. Raymond
2000-12-27  6:36                       ` Norman Walsh
2000-07-07 14:42                         ` Norman Walsh
2000-12-27  6:36                     ` Derek Simkowiak
2000-12-27  6:36                     ` Mark Galassi
2000-12-27  6:36       ` Crash-course to DocBook Eric Bischoff
2000-12-27  6:36         ` Mark Johnson
2000-12-27  6:36           ` Eric Bischoff
2000-12-27  6:36         ` Peter Toft
2000-12-27  6:36       ` I'm trying to set up docbook-tools Norman Walsh
2000-07-07  7:49         ` Norman Walsh
2000-12-27  6:36 ` Mark Galassi
2000-07-04  8:05   ` Mark Galassi
2000-12-27  6:36   ` Eric S. Raymond
2000-07-04  8:22     ` Eric S. Raymond
2000-12-27  6:36     ` Chuck Mead
2000-07-04  8:45       ` Chuck Mead
2000-12-27  6:36     ` Mark Galassi
2000-07-04  8:27       ` Mark Galassi
2000-12-27  6:36       ` Eric S. Raymond
2000-07-04  8:45         ` Eric S. Raymond
2000-12-27  6:36     ` Norman Walsh
2000-07-07  7:49       ` Norman Walsh
2000-12-27  6:36 David C. Mason
2000-12-27  6:36 Peter Ring
2000-07-07  2:27 ` Peter Ring
2000-12-27  6:36 ` Eric Lee Green
2000-12-27  6:36 Volker Paul
2000-12-27  6:36 Gregory Leblanc
2000-12-27  6:36 ` Mark Galassi
2000-07-04 15:44   ` Mark Galassi
2000-12-27  6:36 Peter Ring
2000-12-27  6:36 ` Eric Bischoff
2000-08-14 23:07   ` Eric Bischoff
2000-12-27  6:36   ` Volker Paul
2000-08-16  6:57     ` Volker Paul
2000-12-27  6:36     ` Norman Walsh
2000-08-16  7:30       ` Norman Walsh
2000-12-27  6:36       ` Eric Bischoff
2000-08-18  4:11         ` Eric Bischoff
2000-12-27  6:36         ` b_maddy_016
2000-12-27  6:36           ` Eric Bischoff
2000-08-18  5:55             ` Eric Bischoff
2000-12-27  6:36 Gregory Leblanc
2000-12-27  6:36 ` Eric Lee Green

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20000706195444.D27191@thyrsus.com \
    --to=esr@thyrsus.com \
    --cc=docbook-tools-discuss@sourceware.cygnus.com \
    --cc=ed@redhat.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).