Subject: Re: DSSSL Documentation Project From: Paul Prescod <papresco@xxxxxxxxxxxxxxxx> Date: Tue, 20 Jan 1998 16:15:23 -0500 |
Let me state first that I have no doubt that the goal of a coherent, consistent online DSSSL text is more appealing than that of an affiliation of tutorials. Let me phrase my suggestion another way: perhaps our first goal should be *coverage* of the entire DSSSL language rather than *linear coherency* of coverage. If we get coverage alone (with some overlap, some false leads, some missing links, etc.) then we will have accomplished something great. We could then refashion our texts into a coherent whole. Yes, this way takes more work, but it increases the possibility of us reaching the first level, which we did not the last time we attacked the problem. If we have the enthusiasm and time to pull off coherency and consistency in one shot, then great. But let's go into the venture with eyes wide open. Tony Graham wrote: > > We developed an outline first so that we could be coherent and reduce > the overlap in what various people wrote. Right now we have more than > 400 potential reviewers reading this list, and I expect that if > something is not coherent or not consistent, then someone will point > it out; I don't think coherency is our problem. I'm happy to be proven wrong. I just tend to think that technical writing has many of the same problems as software development. Organizing 10 people to write a 20,000 line computer program is much more work than asking them each to write a single 2,000 line program. Jade is made up of modules, but I don't think it would have been developed if 10 C++ knowledgable programmers had set out to each write a module. The "Mythical Man Month" problems would compound the problems of distributed development and volunteer initiative. Documents are more linear, which makes things a little easier, but there are still alot of connection points between them (where is this term defined, how do these concepts relate, etc.) and in my experience, maintaining those is hard. On top of the literary challenges, there are the problems of learning/installing the standard DTD, sending updates to the maintainer, routing commentary to the right person, updating in unison as information changes and so on. The LDP has an advantage over us because Linux is way too big and complex for them to even *consider* a single book that covers it all. Rather there are many books and tutorials, each written by a single author. > With no disrespect to Ken, just because Ken has said that he is > writing a book on DSSSL doesn't mean that a group of us can't also > write a book on DSSSL. The fact that someone once wrote a book on > HTML doesn't seem to have stopped other people also writing books. True enough. Competition with print authors is just another issue to consider. It isn't a killer argument. > Having documents scattered around the web makes the most sense if you > have a fast, permanent Internet connection. Sometimes you want a > local copy because you're not always connected or you connect only > through a thin pipe, and for some people a lot of the time paper is > better. I agree. > As I understand it, Linux documentation uses the "LinuxDoc" DTD and > toolset, and that "LinuxDoc" tools have since been renamed > "SGML-Tools". Marking up the DSSSL documentation with a single DTD > makes the same sort of sense as standardising the Linux documentation > did to the Linux folks. I believe in standards as much as the next person. I also believe that adhering to them is more work. Like the rest of you, my "day job" is encouraging organizations to make that investment. But I also get paid to tell them when they should consider backing off, rather than risking failure. Again, if we agree that we have the energy to do the whole thing, great. I'm a natural pessimist. <ASIDE>The LDP seems to use LaTeX for some or most of their larger documents: http://sunsite.unc.edu/mdw/LDP-Manifesto.html . I'm not a very big fan of SGML-Tools, so this doesn't bother me very much. Perhaps a good project for this mailing list would be making the DocBook stylesheets and Jade as easy to use and widely distributed as the SGML-Tools.</ASIDE> > Since you don't appear to have that already but do know what it is > that people want to know, do you want to write it? Yes, I can write that, whichever way we decide to go. But I know myself and I know that I will probably write it sooner if I know it is merely a matter of building on my own tutorial, in my existing DTD and putting it on my website rather than figuring out what DocBook elements to use, submitting to reviewers, waiting for comments, updating, resubmitting, comparing to other's parts, making links etc. etc. Every round of communication provides another opportunity for me to procrastinate. :) Paul Prescod -- "You have the wrong number." "Eh? Isn't that the Odeon?" "No, this is the Great Theater of Life. Admission is free, but the taxation is mortal. You come when you can, and leave when you must. The show is continuous. Good-night." -- Robertson Davies, "The Cunning Man" DSSSList info and archive: http://www.mulberrytech.com/dsssl/dssslist
Current Thread |
---|
|
<- Previous | Index | Next -> |
---|---|---|
Re: DSSSL Documentation Project, Tony Graham | Thread | Re: DSSSL Documentation Project, Steve Roggenkamp |
Formatting an Address - a solution, Chuck Darney | Date | Re: DSSSL Documentation Project, Steve Roggenkamp |
Month |