OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

oslc-core message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: Re: [oslc-core] Making it easier to write (and read) domain specs (topic for next meeting?)


Martin, thanks for sharing some of this.  I just want to say, I have made NO assumption that we'll be using the format we have been using for 2.0 specs at open-services.net.  I has started the discussion and sketch [1] of what we want key sections we want in the spec and following OASIS guidelines.  I'll include some more thoughts inlined below.

[1]: https://wiki.oasis-open.org/oslc-core/SpecRoadmap#Spec_Structure  (fairly light on details, planning on using upcoming core and ccm specs to flush it out)

Thanks,
Steve Speicher
IBM Rational Software
OSLC - Lifecycle integration inspired by the web ->
http://open-services.net

<oslc-core@lists.oasis-open.org> wrote on 07/14/2014 08:43:06 AM:

> From: Martin P Pain <martinpain@uk.ibm.com>

> To: oslc-core@lists.oasis-open.org
> Date: 07/14/2014 08:43 AM
> Subject: [oslc-core] Making it easier to write (and read) domain specs
> (topic for next meeting?)

> Sent by: <oslc-core@lists.oasis-open.org>
>
> As part of writing the OSLC Actions Specification and OSLC Availability
> Specification (as part of the OSLC Automation WG), there are a few things
> that have come up that I think we could address in v3 to make it easier both
> to write specs and to read specs.
>
> (tl;dr? Find the "***" markers)
>
>
> Firstly, a small idea:
>
(see other thread)

> Second, larger idea:
>
> In the Actions spec, in some areas rather than saying "the client MUST" we
> said "in order to do X, the client performs steps A, B and C". So rather
> than normative requirements, just defining what it means to do a certain
> thing. Then the client can decide whether or not it wants to do X, rather
> than confusing the spec with conditional MUSTs on the client. Do you think
> this is a pattern or an anti-pattern?
>
> So, I wonder if it would be easier to write the domain specs (less so the
> core specs) if we actually tried to reduce the number of MUSTS - especially
> on the client - and defined things more as "in order to do X, the client
> performs steps A, B and C" for the client, and "in order for the server to
> expose/afford L, it does/exposes/sets M, N O and P". I guess I ought to come
> up with some examples, but I'm a little short on time right now. There would
> still have to be some MUSTs ("if the server/client does F, then it MUST do G").
> We might then be able to be more scenario-driven (which would make reading
> easier) as it's less a collection of MUSTs and MAYs, and more a definition
> of how to achieve things. We could then put the MUSTs that we do need for
> minimum interoperability into a "conformance" section, which references the
> other definitions of how to do things for its full normative meaning.
> (Perhaps some specs already tried doing this, but it's not what I've picked
> up from my reading & editing.)
> I expect this would avoid the need for some of the boilerplate in the domain
> specs, such as the tables of MAYs/MUSTs for media type support & dialog/
> query capability support for each resource type, unless it really needed to
> set these to something specific (it could refer back to core for some
> defaults). I also find the lists we have in the "compliance" sections at the
> moment (e.g.
http://open-services.net/wiki/automation/OSLC-Automation-
> Specification-Version-2.0/#Compliance) to take up a lot of space with not
> much value to the meaning of the spec, and making it harder to read If these
> were scenario- or behaviour-oriented (and those scenarios or behaviours then
> stated that they had a dependence on things like unknown properties and
> content, perhaps transitively through a behaviour such as "to create a
> resource using a Creation Factory").
> (We could trial this with the Availability Specification - which is about
> automation for controlling high-availability & redundancy groups of systems).
>
> *** The best I can come up with a concrete for a proposal here is "to make
> the compliance tables and domain spec definitions more scenario- or behaviour-oriented
> ", but that's a bit abstract. ***
>


I think each spec taking a different approach might be an anti-pattern.  I think including a human-friendlier definition of "what this conformance clause is trying to say" would be good.  Having that human-friendly text being the scenario that motivates the conformance clause seems handy.  I could imagine providing a toggle in the HTML that could allow some of the gorpy conformance stuff to be collapsed.  So some type of structure such as:
<scenario1>
  <conformance statement>
<scenario2>
  <conformance statement>

Or some other organization like this.  Having actual samples of usage within this would be very useful as well.

I think the compliance tables are difficult to manually keep up with.  With moving to the HTML+JS(respec) versions, we could easily generate supporting tables if needed.

>
> So, can you follow those two trains of thought? And do you agree or disagree
> with the direction? If I haven't made myself clear (or used too many words)
> let me know.
>
> Thanks,
>
> Martin Pain
> Software Developer - Green Hat
> Rational Test Virtualization Server, Rational Test Control Panel
> OASIS Open Services for Lifecycle Collaboration - Automation technical committee chair

>
> E-mail: martinpain@uk.ibm.com
> Find me on: [image removed]  and within IBM on: [image removed]  

>
> [image removed]

>
>
>
>
> IBM United Kingdom Limited
> Registered in England and Wales with number 741598
> Registered office: PO Box 41, North Harbour, Portsmouth, Hants. PO6 3AU
> 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
>
> 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]