From mboxrd@z Thu Jan 1 00:00:00 1970 From: "Eric S. Raymond" To: "Edward C. Bailey" 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 Message-id: <20000706195444.D27191@thyrsus.com> References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> <873dlnjklb.fsf@nwalsh.com> <20000706131959.A25726@thyrsus.com> <20000706150802.A26225@thyrsus.com> <20000706180129.C26696@thyrsus.com> X-SW-Source: 2000/msg00240.html Edward C. Bailey : > 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... -- Eric S. Raymond "Rightful liberty is unobstructed action, according to our will, within limits drawn around us by the equal rights of others." -- Thomas Jefferson From mboxrd@z Thu Jan 1 00:00:00 1970 From: "Eric S. Raymond" To: "Edward C. Bailey" 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 Message-ID: <20000706195444.D27191@thyrsus.com> References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> <873dlnjklb.fsf@nwalsh.com> <20000706131959.A25726@thyrsus.com> <20000706150802.A26225@thyrsus.com> <20000706180129.C26696@thyrsus.com> X-SW-Source: 2000-q3/msg00038.html Message-ID: <20000706164600.sdvDb7uMULvjfHXLnhkbb9lYACfEXIHQrV-rSKnvpGQ@z> Edward C. Bailey : > 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... -- Eric S. Raymond "Rightful liberty is unobstructed action, according to our will, within limits drawn around us by the equal rights of others." -- Thomas Jefferson