sca-bindings message
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]
Subject: Suggested documentation standards for SCA specification documents
- From: Simon Holdsworth <simon_holdsworth@uk.ibm.com>
- To: OASIS Bindings <sca-bindings@lists.oasis-open.org>
- Date: Mon, 22 Jun 2009 13:09:58 +0100
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
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]