obix message

Subject: [OASIS Issue Tracker] Created: (OBIX-94) Narrative style not appropriate for a standard

From: OASIS Issues Tracker <workgroup_mailer@lists.oasis-open.org>
To: obix@lists.oasis-open.org
Date: Fri, 21 Feb 2014 02:55:11 +0000 (UTC)

Narrative style not appropriate for a standard
----------------------------------------------

                 Key: OBIX-94
                 URL: http://tools.oasis-open.org/issues/browse/OBIX-94
             Project: OASIS Open Building Information Exchange (oBIX) TC
          Issue Type: Improvement
          Components: OBIX 1.1 Specification
    Affects Versions: OBIX 1.1 XSD PR02
         Environment: TAB Review
            Reporter: Toby Considine
            Assignee: Toby Considine


"The style of the narrative reads more like a user guide than a standard. 

- In many places, the author uses ""we"". That should be generally avoided. E.g.: ""..., we typically don't allow defaults to be used"" --> replace with ""...default values are generally not allowed"". 

- ""There isn't much more to say about implicit Contracts other than it is recommended that a human brain be involved. "" Such an expression is hard to parse as of its exact meaning (even more so for a non-native speaker...): to avoid. 

- Casual style belongs more to a primer or user guide: ""So now let's look at the rules governing the explicit Contract."""

-- 
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://tools.oasis-open.org/issues/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira