Suggested documentation standards for SCA specification documents

[Simon Holdsworth <simon_holdsworth@uk.ibm.com>]

Folks, following some review comments
from the bindings specs, I'd like to propose some high-level standard formatting
that all our SCA specs follow - we're not currently very consistent across
or within documents.  There would be more details if we want complete
consistency, but the following is a start to test people's reactions, and
consistency on these would go a long way to a common look and feel.  Copying
to bindings and assembly for initial reactions, and those are the specs
I've looked at in this regard.

If this is something we should not be
worrying about until later in the publication cycle, feel free to ignore
for now...

Normal text ("Normal")

Arial 10pt, align left, before 4pt after
4pt, line spacing single, indentation 0

Currently used by JMS and JCA and Assembly
up to section 3 and section 12 onwards;  WS and Assembly section 3
to section 11 use:  Verdana, align left, before 0pt after 6pt, line
spacing single, indentation 0.63.  Exceptions within Assembly (Section
10.4 uses Arial, not Verdana, Section 11 varies per paragraph)
Assembly also inconsistent in indent
(section 7.6, WSDL Interface Type, section 10.4  has no indent, most
other text is 0.63 indent)

XML, code examples ("Code"):

Courier New 9pt, align left, before
0pt after 0pt, line spacing single, indentation 0.76 right and left, grey
background; attributes names in purple (127,0,127), constants in blue (42,0,255),
<, > and /> in green, other text in black.   Indentation
using 3 spaces per level, no tabs

Currently used by JMS and JCA;  WS
uses:  indentation 0.63 left, 0.76 right; Assembly uses Courier New
10pt, white background

External references use full reference
name plus tag:

name of external reference [tag]  
for example SCA Assembly Specification [SCA-Assembly].  The name and
tag should both be hyperlinked to the appropriate line in the reference
section

Reference to elements and attributes
in a schema or instance use Courier New 10pt, and include "attribute"
or "element":

the service
element;   the @uri
attribute;   the inboundConnection/resourceAdapter
element

Where references are to the runtime
implementation these should not be highlighted, e.g.  "For an
SCA service with JMS binding, the SCA runtime...."

This formatting not currently used anywhere, but my feeling is this makes
it consistent with the presentation of the attributes/elements in the Code
sections.

Regards, Simon

Simon Holdsworth
STSM, SCA Bindings Architect; Master Inventor; OASIS SCA Bindings TC Chair
MP 211, IBM UK Labs, Hursley Park, Winchester SO21 2JN, UK
Tel +44-1962-815059 (Internal 245059) Fax +44-1962-816898
Internet - Simon_Holdsworth@uk.ibm.com

---

Unless stated otherwise above:
IBM United Kingdom Limited - Registered in England and Wales with number 741598.
Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6 3AU