SM> Strawman for a PWG IEEE-ISTO Template for PWG Proposed Standards

SM> Strawman for a PWG IEEE-ISTO Template for PWG Proposed Standards

Hastings, Tom N hastings at cp10.es.xerox.com
Wed Jan 29 17:19:11 EST 2003


In case there is time at the end of the SM telecon tomorrow, Thursday, Jan
30, 1-2 PM EST (10-11 PST) after we discuss the PWG Process, here is a
Strawman for a PWG IEEE-ISTO Template for PWG Proposed Standards.

This is a one-time notification to both reflectors. Further on-line
discussion of the PWG Template with occur ONLY on pwg at pwg.org, NOT on the
sm at pwg.org (same as for any other PWG process discussion). 

Dennis Carney, Ira McDonald, Ron Bergman, and I have been working on an
MS-WORD template for PWG IEEE-ISTO standards for use by all the PWG WGs
doing IEEE-ISTO standards.  Here is version 0.2 as a strawman.  

ftp://ftp.pwg.org/pub/pwg/general/templates/pwg-template-for-standards-lates
t.pdf
ftp://ftp.pwg.org/pub/pwg/general/templates/pwg-template-for-standards-lates
t.doc
ftp://ftp.pwg.org/pub/pwg/general/templates/pwg-template-for-standards-v02-0
30127.pdf
ftp://ftp.pwg.org/pub/pwg/general/templates/pwg-template-for-standards-v02-0
30127.pdf

Ira and I made some simplifications in it as part of making version 0.2 over
the IEEE-ISTO style as documents below in Appendix C which also described
why we made each change.  Ira and I haven't had a chance to talk to anyone
else about many of these simplifications.  

ISSUE:  So an imporant issue is whether these simplifications are OK or do
we need to rigorously follow the IEEE-ISTO standard style?  

The rest of version 0.2 is incorporating the detailed commens that Dennis
Carney had made as a result of trying to use a template while he wrote up
his "-actuals" IPP specification. 

There is a companion document: "Tips for Good Technical Writing" which I
moved from the Appendix to a separate document available at:
ftp://ftp.pwg.org/pub/pwg/general/templates/good-writing-tips-latest.pdf
ftp://ftp.pwg.org/pub/pwg/general/templates/good-writing-tips-latest.doc
ftp://ftp.pwg.org/pub/pwg/general/templates/pwg-template-for-standards-v02-0
30127.pdf
ftp://ftp.pwg.org/pub/pwg/general/templates/pwg-template-for-standards-v02-0
30127.pdf

Please send comments.

Thanks,
Tom


Appendix C	Differences between this Template and the IEEE-ISTO standard
style
This Appendix lists the differences between this Template and the IEEE/ISTO
standard style and explains why.  The IEEE-ISTO standard style is
represented in the IEEE/ISTO 5101.1 Media Name Standard.  These differences
have evolved after experience using the IEEE/ISTO standard style for online
viewing and printing with Adobe Acrobat.  The differences are (working top
to bottom):
	1.	Merged the redundant second page (which had the Abstract)
onto the first page and got rid of the second page.  Our understanding is
that having two title pages comes from publishing the document in printed
form, where the first page is like a cover.  Most standards bodies have
eliminated the cover so that the Abstract appears on the first page.
	2.	Added "(PWG)" after "The Printer Working Group" in the
title.
	3.	Removed the redundant indications of whether this version is
a Working Draft, a Proposed Standard, a Draft Standard, or a Standard from
the Header.  Only the title indicates the status.  A Working Draft has:
"Working Draft for a PWG Proposed Standard".  A Proposed Standard after
passing WG Last Call will have: "PWG Proposed Standard".  A Draft Standard
after passing WG Last Call will have: "PWG Draft Standard".  A Standard
after passing PWG Last Call will have:  "PWG Standard"
	4.	Added the URL for the document on the first page, so that it
is easy to find.
	5.	Added Editor's name(s) to the first page, so that proper
credit is given as is common in some standards bodies.
	6.	Simplified the headers and footers, so that the headers are
all the same except for the first page.  Keeping the headers and footers
simple will reduce errors in producing drafts and allow editor's to focus on
content more and format less.  
	7.	The Left side of the Header is blank for Working Drafts,
then gets IEEE-ISTO 51nn.n after the Working Draft passes WG Last Call.
Thus the editor only changes the Header once, when the specification passes
Last Call.  
	8.	In the Header, the Title is centered with most of the fixed
parts removed.
	9.	In the Header, the page number is always on the right.  The
IEEE-ISTO format did not have the page number on the top at all, which has
proved a problem when viewing the specification with Adobe Acrobat, when the
user can only see part of the page at one time.  Also scrolling upwards and
downwards needs the page numbers to be at the top and bottom.  
	10.	The Footer follows the IEEE-ISTO style, except the page
number is always centered, instead of alternating left and right.  This
makes it easier to spot the page number when viewing it on the screen.
	11.	Page numbers in the Header and Footer, start at 1 with the
first page.  No Roman numerals are used.  This makes it easier to relate
pages as numbered by Adobe Acrobat and those printing on each page and in
the Table of Contents.  Also when printing out selected pages, the page
number used by the Printer driver agree with the printed page numbers.
	12.	Defined the Body Text style to use ragged right, rather than
justified, in order to make the document more readable by people when
printed or displayed though it may not look as pretty.
	13.	Added editor names for PWG standards in the References
section, as is practice in some standards bodies and most technical
publications.
	14.	Removed the first initials from references and used only
family names as is becoming practice to avoid the cultural confusion about
whether family names come first or last.

Here is the change log:
	Changes to make version 0.2, January 27, 2003
The following changes were made to create version 0.2, January 27, 2003
after careful review by Dennis Carney and Ira McDonald:
	1.	Generalized the template so that it can be for any PWG
standard, not just IPP.
	2.	Simplified the template so that as few fields as possible
have to be updated as the specification progresses through the process -
otherwise everyone does it differently.
	3.	Follow the IEEE-ISTO style with the exceptions listed in
Appendix C derived from experience viewing and printing on-line versions
using Adobe Acrobat.
	4.	Explained the file naming scheme for PWG WGs.
	5.	Added the requirements for a Logical Diagram and a
Configuration Diagrams and showed some IPP examples.
	6.	Highlighted IPP specific instructions and examples in green,
like this, in order to give real examples, but make the Template work for
all PWG Working Groups
	7.	Added RFC 3380, 3381, 3382.
	8.	Added a number of terms that may be useful to PWG projects
other than IPP.
	9.	Moved the Appendix "Tips for Good Technical Writing" to a
separate document available at:
ftp://ftp.pwg.org/pub/pwg/general/templates/good-writing-tips-latest.pdf





More information about the Sm mailing list