Cart
|
[XML-DEV Mailing List Archive Home] [By Thread] [By Date] [Recent Entries] [Reply To This Message] Re: Improved writing -- who's going to pay for it?
 In a previous post, I said: > > Rick JELLIFFE wrote: > > > So would people be happier with > > * a much more comprehensive Primer > > I agree with Miloslav on this one. The primer is a stop-gap and if you > fixed the spec, you wouldn't need it. I think a better idea would be to > mix the primer with the regular spec (see Examples, below). and: > > * a much terser algorithmic/logical treatment of the subject, less > > comprehensible to Joe Database but smaller and more precise > > Definitely the wrong direction. This would, on the other hand, be a very > useful thing to throw into an appendix, with a note that if the appendix > disagrees with the rest of the spec, the appendix is right. I would like to plead semi-advanced brain death. Traditional documentation is split roughly into user's guides (which give the big picture and walk you through the most important details) and reference material (which give all the details in fairly terse form). One of the problems with specs is that they are primarily reference material, but generally have a bit of user's guide thrown in. It is therefore generally very difficult to learn about a topic from a spec alone -- sort of like trying to figure out what a puzzle looks like by only viewing the pieces. For ISO/ANSI/etc. specs, this isn't much of a problem. These usually come after the fact, and people read them for details: they already know the big picture, having usually had years of experience. If not, there are plenty of books around to get them going. The W3C is in a somewhat unique position, attempting to introduce new material in spec form. This generally frustrates people who are reading the spec for the first time, since the spec lacks adequate user's guide material and, because the subject is often new, there is no other material to read for background. In some cases, the ground covered by the spec is conceptually simple enough that a short introduction/overview in the spec gives the reader enough information to wade through the details. The XSLT and XML specs are good examples of this (XSLT especially). Therefore, my suggestion to pitch the primer now strikes me as idiotic -- in fact, it's the ideal situation and provides material to get people going, which is exactly what they need. Similarly, my suggestion to merge the primer into the structures spec strikes me as equally idiotic -- all it will do is make the structures spec harder to use as reference material, as somebody pointed out last week. However, I would like to say that good reference material generally does, for each item, contain a sentence or two giving context and motivation and a very short example. I do think this would be a good idea in the structures spec. Lapsing towards early senility, -- Ronald Bourret Programming, Writing, and Training XML, Databases, and Schemas http://www.rpbourret.com 
|
PURCHASE STYLUS STUDIO ONLINE TODAY!Purchasing Stylus Studio from our online shop is Easy, Secure and Value Priced! 
Download The World's Best XML IDE!Accelerate XML development with our award-winning XML IDE - Download a free trial today! Subscribe in XML format
|
|||||||||
