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?)
- From: Steve K Speicher <sspeiche@us.ibm.com>
- To: Martin P Pain <martinpain@uk.ibm.com>
- Date: Thu, 17 Jul 2014 08:38:45 -0400
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]