RE: OASIS TC specs style guide?

["Karl F. Best" <karl.best@oasis-open.org>]

Lofton:

Good comments.

> I see that you have copied Eve Maler, and so you will get (in
> detail) what
> I will mention.  In the SVG WG, we have just started to pick up and use
> some DTDs and stylesheets that are gaining ground in W3C for
> authoring the
> specs.  I'm pretty sure I saw Eve's name in the revision history of the
> DTDs.  I'm not sure what authoring tools are good to use, as I haven't
> started using the XML authoring yet.

That's been my concern with requiring people to use XML; authoring tools are
not yet ubiquitous -- certainly not to the same extent as MSWord. But OASIS
is in the business of promoting XML; shouldn't we use our own tools?

> Also you might query the W3C publishing people -- they were at the QA
> workshop.  Susan Lesch, I think was the person (see the attendance roster
> for contact info).  As you recall from WSQA, as soon as you start
> discussing document standards, it quickly becomes a bigger topic than
> "what's a handy format?"

Yes, I chatted briefly with Susan at that meeting, and our conversation is
actually what got me starting to think about this topic. I'm aware that
there are other specs/guidelines out there; I just want to hear from you
chairs what you think about them.

> I would suggest that this topic might deserve a little more
> formal standing
> than just pulling together a handful of suggestions into a guidelines
> document.  A discussion list might be good, at
> least.

Yes, that may be a good idea. I don't think this needs to be a full-fledged
OASIS TC, but it may noot hurt to get more folks in on the discussion, so a
discussion list may be an answer. I'm afraid, though, that many people will
see this sort of discussion as "overhead" and taking them away from
technical work. So I thought that I would start small and see where it goes
from there.

> (I have copied Lynne and Ken on my reply, as they each might have some
> comments on my latter assertions.  Maybe Lynne, as chair of the
> Conformance
> TC, might have some TC history or agenda interest about this.)

Lynne and Ken got this, as they are TC chairs. Can we use this list to
continue the discussion?


</karl>
=================================================================
Karl F. Best
OASIS - Director, Technical Operations
978.667.5115 x206
karl.best@oasis-open.org  http://www.oasis-open.org


> -----Original Message-----
> From: Lofton Henderson [mailto:lofton@rockynet.com]
> Sent: Friday, July 13, 2001 12:08 PM
> To: Karl F. Best
> Cc: eve.maler@east.sun.com; lynne Rosenthal;
> gkholman@cranesoftwrights.com
> Subject: Re: OASIS TC specs style guide?
>
>
> At 11:26 AM 7/13/01 -0400, Karl F. Best wrote:
> >[...]
> >I would like to get your suggestions for various formats,
> stylesheets, etc.
> >that would be good recommendations for TCs writing
> specifications. Are there
> >good templates available from other standards organizations? Or how about
> >simply guidelines without templates? I suppose that it's easiest
> for TCs to
> >use MSWord,
>
> I finally stopped authoring in MS Word a year or two ago.  My
> last specs --
> for SVG conformance stuff -- were in MS Word, which I exported to
> HTML.  Huge messy HTML.  W3C 'tidy' (plus some manual
> intervention) cleaned
> these up.  I now author in HTML directly, using Dreamweaver and/or
> Amaya.  Dreamweaver is nice about preserving your input HTML fairly
> faithfully on output.  Amaya does the same, and is free, but I have found
> it not quite as solid as Dreamweaver.  There are others.
>
> But see below...
>
> >but what about writing in XML using OASIS' own DocBook?
>
> I see that you have copied Eve Maler, and so you will get (in
> detail) what
> I will mention.  In the SVG WG, we have just started to pick up and use
> some DTDs and stylesheets that are gaining ground in W3C for
> authoring the
> specs.  I'm pretty sure I saw Eve's name in the revision history of the
> DTDs.  I'm not sure what authoring tools are good to use, as I haven't
> started using the XML authoring yet.
>
> Also you might query the W3C publishing people -- they were at the QA
> workshop.  Susan Lesch, I think was the person (see the attendance roster
> for contact info).  As you recall from WSQA, as soon as you start
> discussing document standards, it quickly becomes a bigger topic than
> "what's a handy format?"
>
>
> >Please send your suggestions that I can include in the
> Guidelines. To go a
> >step further, I wouldn't mind seeing a discussion on this list
> that may lead
> >to some sort of consensus about which is best to use.
>
> I would suggest that this topic might deserve a little more
> formal standing
> than just pulling together a handful of suggestions into a guidelines
> document.  A discussion list might be good, at
> least.  Reason:  (standard/spec) document format has ramification that go
> beyond universal readability and document maintenance.  It can be
> intimately tied to conformance work, as we're seeing now in the
> XSLT/Xpath
> TC.  Life would have been a lot easier if an XML version of XSL were
> normative (instead of only the HTML output document).
>
> (I have copied Lynne and Ken on my reply, as they each might have some
> comments on my latter assertions.  Maybe Lynne, as chair of the
> Conformance
> TC, might have some TC history or agenda interest about this.)
>
> Regards,
> -Lofton.
>
>
> *******************
> Lofton Henderson
> 1919 Fourteenth St., #604
> Boulder, CO   80302
>
> Phone:  303-449-8728
> Email:  lofton@rockynet.com
> *******************
>
>