Re: SSTC document guidelines

[Jeff Hodges <jhodges@oblix.com>]

"Eve L. Maler" wrote:
> 
> Here are just a few comments on the SSTC Document Guidelines

Some comments on Eve's comments. Others have thoughts to contribute?

thanks,

JeffH


> At 12:52 AM 1/31/01 -0800, Jeff Hodges wrote:
> >Bob & I collaborated on modifying the document guidelines doc he posted last
> >week. Present OASIS-specific version is below. Comments encouraged.
> >

[..snip..]

> >
> >3.2  Naming
> >
> >Committee documents MUST be named using the format:
> >
> >    "draft-sstc-" + [ subcommittee mailing list acronym + "-" ]
> >     + short title + "-" + two-digit version + "." + doc format
> >
> >    e.g. "draft-sstc-core-assertions-05.html".
> 
> For HTML documents, any chance we can standardize on either .htm or .html,
> but not both?  It would be annoying for people to guess wrong on the
> extension, when the rest of the filename is so well structured.

I'm professionally agnostic, I agree we should just pick one and solicit input
from others (tho I personally favor ".html" since ".htm" is pretty much just a
holdover Windows-ism (if I understand the lineage correctly)). 

I just asked Karri Myles, our webmaster, what he thinks -- he's going to be
doing a fair amount of the work managing the SSTC pages -- and he favors
".html". 



> >Individual submissions MUST be named using the format:
> >
> >    "draft-" + main author's last name + "-" + short title
> >      + "-" + two-digit version + "." + doc format
> >
> >    e.g. "draft-morgan-coolidea-00.txt".
> >
> >
> >5.3  Formats
> >
> >PDF format is preferred distribution document format. Document
> >source formats are XML encoded according to the XXX DTD for text,
> >and Powerpoint source for illustrations (one illustration per
> >powerpoint slide, one powerpoint file containing multiple slides
> >per corresponding XML textual source file).
> 
> Was PDF the agreement of the folks who collaborated on these guidelines?  I
> thought we were going for HTML.  

.html is the desired-by-BobB, "interim", work-product editable format, as
discussed in these messages..

http://lists.oasis-open.org/archives/security-services/200101/msg00094.html
http://lists.oasis-open.org/archives/security-services/200101/msg00095.html

..and the non-editable, "output format" (or "distribution document" format) is
presently agreed upon to be .pdf (see the above two msgs).


> Also, I'd like to standardize on JPEG, at
> least as the "non-revisable" version of a graphic.  Just about anything can
> output .jpg.

Yes. Again, referring to the above two msgs, .ppt is the presently-agreed-upon
"source" format for illustrations, while .jpg is the "non-revisable" aka
"output format" aka "distribution format" for illustrations. 


> 
> >5.4  Content elements
> >
> >A document must include, at the beginning, the author's names, the
> >date of submission, the document name including version number, the
> >name of the working group, and an email address to which comments can
> >be directed.  A document must include, at the end, author contact
> >information for all authors, including at least an email address for
> >each.
> 
> I would like to see all the "metadata," including author contact
> information, at the top so that it's all in one place.  Of course, if we
> use sufficiently structured XML (e.g. XMLspec or a derivative), we can
> generate the output to put this stuff in any order we like.
> 
> FWIW, here's what W3C documents typically have in the header; these
> examples are taken from http://www.w3.org/TR/REC-xml and they're all
> formally covered in the XMLspec DTD.  I think it would be nice to have at
> least all those with *:
> 
> *Title (e.g., "Extensible Markup Language (XML) 1.0 (Second Edition)")
> Type of document (e.g., "W3C Recommendation")
> *Date of publication (e.g., "6 October 2000")
> *Official URI of publication (e.g.,
> "http://www.w3.org/TR/2000/REC-xml-20001006")
> Generalized URI of latest version
> URI for most recent previous version
> *Authors/editors and contact information
> Copyright statement
> *Abstract
> *Status of This Document
> 
> This week I will attempt to make a derivative of XMLspec (or simply its
> stylesheets) that might meet our needs.

Super, that'd be great. Sure, we're open to revising where in the doc metadata
oughta be placed. 

I think we should include "type of document" in your * list. And, to the extent
that it's pretty easy to do (see the end of draft-sstc-doc-guidelines-02.txt;
we can provide a .txt and/or .html file template), subcomm and TC drafts SHOULD
have the IPR and Copyright notices placed in them. 



[..snip..]