From mboxrd@z Thu Jan 1 00:00:00 1970 From: "David C. Mason" To: 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: References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> X-SW-Source: 2000/msg00217.html > > I'm trying to set up docbook-tools, and finding it a hideously > > frustrating experience. Why does all the SGML software and > > documentation in the world read as though it was carefully designed > > to prevent any actual document production from getting done? This is one of those cases where certain documentation projects have taken up the call more so than the tools side. For example, both the GNOME and KDE doc groups have manuals to help people get involved with writing documentation for their projects. Both tell the writer where to get everything they need for Docbook and how to use it - but both also describe it in terms that are particular to their style of writing. I like this approach as it narrows the focus to projects and those who wish to write for those projects. Outside of that the best resources I have seen are Mark's tutorial and Deb Richardson's HOWTO at OSWG. The main problem with it is that describing SGML is not as trivial as you might think. Describing DocBook is easier, but it still comes as very foreign to those who come from either the word processor world, or the format driven mark-up world. The best way to learn is by trying, not by reading IMHO. Can the documentation be better? Sure it can, and we shall try. Still, I find it somewhat humorous at the trouble many hackers (who would never dream of documenting their code) have when they can read the source :-) Cheers, Dave -- David Mason Red Hat AD Labs dcm@redhat.com http://people.redhat.com/dcm From mboxrd@z Thu Jan 1 00:00:00 1970 From: "David C. Mason" To: docbook-tools-discuss@sourceware.cygnus.com Subject: Re: I'm trying to set up docbook-tools... Date: Wed, 05 Jul 2000 07:41:00 -0000 Message-ID: References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> X-SW-Source: 2000-q3/msg00015.html Message-ID: <20000705074100.g1BnpdUPI-DjZbuZwxcSs_46XZaq9naCQupqUjzyHeU@z> > > I'm trying to set up docbook-tools, and finding it a hideously > > frustrating experience. Why does all the SGML software and > > documentation in the world read as though it was carefully designed > > to prevent any actual document production from getting done? This is one of those cases where certain documentation projects have taken up the call more so than the tools side. For example, both the GNOME and KDE doc groups have manuals to help people get involved with writing documentation for their projects. Both tell the writer where to get everything they need for Docbook and how to use it - but both also describe it in terms that are particular to their style of writing. I like this approach as it narrows the focus to projects and those who wish to write for those projects. Outside of that the best resources I have seen are Mark's tutorial and Deb Richardson's HOWTO at OSWG. The main problem with it is that describing SGML is not as trivial as you might think. Describing DocBook is easier, but it still comes as very foreign to those who come from either the word processor world, or the format driven mark-up world. The best way to learn is by trying, not by reading IMHO. Can the documentation be better? Sure it can, and we shall try. Still, I find it somewhat humorous at the trouble many hackers (who would never dream of documenting their code) have when they can read the source :-) Cheers, Dave -- David Mason Red Hat AD Labs dcm@redhat.com http://people.redhat.com/dcm