OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

tm-pubsubj message

[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