Re: DSSSL Documentation Project

[Steve Roggenkamp <roggenkamps@xxxxxxx>]

Paul Prescod wrote:
> 
> ...
> 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.

I agree we should attempt coverage first and if we get some overlap, so
be it.  I prefer to have multiple examples, explanations, etc.

...
> 
> True enough. Competition with print authors is just another issue to
> consider. It isn't a killer argument.

Print authors also have the advantage of skilled editors who help insure
a consistent document.

> 
> > 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.

Several CDROM publishers have created collection of documents pertaining
to a given subject.  The Walnut Creek Internet and Ada CDROMs, and the
RedHat Linux Library come to mind immediately. A CDROM publisher could
take a snapshot of the Internet documentation for those who prefer a
local copy.

...
> 
> 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. :)
> 

Using DocBook can be a pain, and there are some things I feel it doesn't
handle very well, but by using it I can piggyback my effort with
others.  Incidentally, I use DocBook for my own personal documentation
when I need to generate multiple output formats.  I've used various
tools to change it into RTF, HTML and TeX.

Steve
-- 
-----
Steve Roggenkamp
InterNet:    roggenkamps@xxxxxxx
Address:     9159 Eversole Run Road
             Powell, OH  43065  USA
Phone:       614.873.6573
WWW:         http://www.infinet.com/~sroggen/home.html


 DSSSList info and archive:  http://www.mulberrytech.com/dsssl/dssslist