[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?
I know that one area that usually throws me is trying to figure out the context or the use of something. Let me pick on XSLT first. They start out with a section on Fallback but never really provide a defintion of what this means to them. I don't think I have ever come across this as a Comp Sci term so what is the general meaning of this facilty. After getting into and reading the section twice (after getting through the whole spec to find the other references to issues and features about this) you get a feel for what it is meant to be used for, but still no clear definition. With Schemas, the primer is a good start, but again it lacks the defintion and explanation of why I might want a feature. There is no context really provided that says, we wanted to improve DTDs, and here are the 5 (more likely 100) things that we wanted to change and improve. If even that simple list was provided and features linked back to the "requirement" that they were being implemented to solve it might help with the understanding. Instead we jump into what feels like the middle of the process and get this laundry list of features. It would be nice if some consistancy in presentation was preserved. XSLT and Schemas have a similar background in that what we have are element definitions that have attributes that need to be explained. Why do I have two different way of presenting the information? In XSLT I see the actual psuedo XML for the various elements, in Schemas we get this table that talks about properties. In just checking the Glossary in the structures spec, I see that it hasn't even been built yet. How many versions has this document gone through? The simple effort of making sure that this was provided and accurate would make reading this spec off line a little more manageable. Anyway, enough rambling from me ... ..dan > > Linda van den Brink wrote: > > > Whereas a tech writer, who is inside > > the organization, would presumably have good communication lines to the > > editors of specs and could ask them 'what is meant here' and THEN come up > > with a good rewrite. > > So would people be happier with > * a much more comprehensive Primer > * splitting the Structures draft into two or three parts that were > more > self contained > * a much terser algorithmic/logical treatment of the subject, less > comprehensible to Joe Database but smaller and more precise > * a rewrite of structures based on the concrete syntax rather than > having the abstract components first > > Knowing some specifics might be helpful. > > Even knowing at what point you become confused might help: I know > paragraph clarification is not Simon's preferred way, but it is > not a waste of time. > > Cheers > Rick Jelliffe >
|
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
|