Semantic Model Mail Archive: SM> Strawman for a PWG IEEE-IST

Semantic Model Mail Archive: SM> Strawman for a PWG IEEE-IST

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

From: Hastings, Tom N (hastings@cp10.es.xerox.com)
Date: Wed Jan 29 2003 - 17:19:11 EST

  • Next message: Hastings, Tom N: "FW: PWG> RE: SM> Updated Process [my comments]"

    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@pwg.org, NOT on the
    sm@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



    This archive was generated by hypermail 2b29 : Wed Jan 29 2003 - 17:19:23 EST