[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Subject: Re: [tm-pubsubj] Recommendations for PubSubj Documentation - version0.2
* Lars Marius Garshol | | - the term "published subjects documentation" seems to be awkward to | use in prose, which makes me think we should change it. One way | would be to add "set", "module", or "package" at the end. That | would make it fit much more naturally into sentences. * Bernard Vatant | | The simpler the better. "set" would be fine for me. But adding | another word does not make it less awkward ... Actually, it does, because the term PSD does not fit properly into sentences without it. I was going to look at the recommendations document for examples, but for some reason it's no longer on the OASIS site. In fact, the entire recommendations directory is gone for some reason. * Lars Marius Garshol | | - section 2 I think should be replaced by explanatory text that | clearly establishes the meaning of each term and its relationship | to the others. An alphabetically ordered glossary is very hard to | learn from, and in any case unnecessary in a hypertext world. * Bernard Vatant | | Why? Don't we have the same thing in XTM spec? We certainly do, and I tried to get Steve to fix that. He agreed with me, but said they didn't have time to fix it before publication. We do have time now... * Lars Marius Garshol | | - most of the definitions in section 2 I think are also too brief. * Bernard Vatant | | "The less you say, the less you go wrong" That's precious little help to the poor non-TM-experts who are the indended audience for this document. We really do need to make things easier for them. * Lars Marius Garshol | | - section 3.1: this is much too brief. We need to go into the why, | and also the how. | | - section 3.2: again much too brief. Also, much of this information | is not useful unless it is provided in machine-processable form. * Bernard Vatant | | Suggestions? I know this is hard to write, but I think we do need to go into the details here. It may be easier to post points via email and have us argue about it there. It is way beyond my capacity to delve into that right now. --Lars M.
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Powered by eList eXpress LLC