OSLC Workgroup Principles, Operations, and Best Practices

NOTE This page is no longer updated , see resources from http://open-services.net and more directly http://open-services.net/participate/workgroup-best-practices/#specification-stages

Guiding Principles for OSLC Workgroups

• Transparency. We are open to participation by anyone. Communication happens in the open via the OSLC wiki, mailing list, and regular workgroup meetings. Meeting schedules, agendas, and minutes are published on the wiki.

• Scenario-driven. We are focused on satisfying real-world interoperability scenarios. We define them in the working group, together, and agree on which scenarios are in scope for a particular specification effort.

• A bias towards the simple/minimum. We avoid over-specifying. We do just enough specification to address the scenarios. No ocean-boiling, and no spec writing for its own sake.

• Time-boxed and incremental. We are highly iterative, preferring to deliver something with implementation behind it in a short period of time (typically 4-6 months), and queuing up additional topics for future spec efforts. It's expected that early specification efforts will select a relatively narrow set of scenarios and a small workgroup in order to get started, and that, with each iteration of the specification, a broader set of scenarios will be tackled by a broader set of workgroup participants.

• Specification coupled with implementation. Having a spec without implementations helps nobody, so we seek to have specs and initial REAL implementations evolve together.

Workgroup Operations

What is an OSLC Workgroup?

Workgroups are the core organizational construct for OSLC specification efforts. A workgroup is simply a group of people who have a common interest in defining specifications that enable lifecycle integrations around a given topic. For instance, the Change Management workgroup is involved in understanding the kinds of services that are valuable in supporting interoperability with Change Management systems. A key scenario taken on by that workgroup is the integration between Quality Management tools and Change Management tools for the creation and disposition of defects found in the test phases of the lifecycle. As in this example, workgroups often tackle integrations that cross lifecycle domains.

Who joins the workgroups? What does joining a workgroup mean? How much time is required?

Workgroup members have a range of skills and perspectives. Some members are part of corporate development organizations, systems integrators, or industry consortiums who have experience in applied use of tools for software delivery; often times, these members have in-house developed tools. In either case, they are interested in improving their organizations' effectiveness in software delivery and in creating greater flexibility in choosing tools to support the work they do. Other members are from software tool vendors or open source communities who see market opportunities and cost savings associated with open interfaces.

Workgroup members can participate in several ways:

1. Authoring/reviewing integration scenarios and helping to decide the scope for a spec iteration.
2. Authoring/reviewing the technical specifications for resources and services needed to support the scenarios.
3. Implementing the services -- either as a service provider or a service consumer -- to validate the spec or achieve the desired integrations.

Involvement in any or all of these activities is valuable. Depending on their interests and skills, it's typical for members to be involved in different activities to varying degrees -- for example, a member may be active in scenario definition but less so in spec authoring or implementation. Team members should expect to spend 30-60 minutes a week on average, and perhaps more during peaks of specification authoring and implementation efforts. Finally, by participating, workgroup members agree to the Terms governing participation, contribution, and IP covenants.

How are workgroups formed?

Workgroups are proposed by contacting the OSLC initiative leaders (KartikKanakasabesan or SteveSpeicher) or posting to the OSLC Core WG mailing list. It is also recommended to copy the general community mailing list as well at community@open-servicesNOSPAM.net. A proposal should include:

1. a brief description of the topic/domain area,
2. the nature of the integrations of interest, the value of the integrations and the motivation for forming the workgroup,
3. a proposed workgroup leader and a list of interested or targeted individuals or organizations.

Proposals should take into account existing workgroup efforts, so as not to introduce overlap or conflict, as well as existing industry specifications or standards. Discussions and refinement of the proposal will typically ensue until the proposal is well-formed enough to be evaluated by the OSLC Leads workgroup, who will review and recommend formation of the workgroup or not. Consideration will be given to the relevance/value of the proposed topic area, consistency with the OSLC architecture and guiding principles, and relationship to other active workgroups.

How do workgroups operate? How are decisions made?

In general, detailed matters of decision making and procedure are left to the workgroups. Established norms and successes are being evolved into a set of best practices that are outlined below. Each workgroup has a different size, scope, makeup, and set of personalities. Some workgroups consist of 3-4 individuals with a very well defined scope, while others are 3 or 4 times as large or with a more ambiguous charter. Some situations or working styles benefit from a more rigorous approach than others. Moreover, some workgroups have the size and capacity to form subgroups or committees to address certain topics and report back to the workgroup. In any case, workgroups should make a point to discuss and document how they plan to operate. Three things are essential:

1. The workgroup lead, who is responsible for driving the workgroup activities, keeping the effort on track, and representing the workgroup.
2. An open dialog -- an atmosphere where listening to and considering the perspectives of each member is valued.
3. Adherence to the OSLC guiding principles -- that is, a pragmatic, minimalist, and incremental approach in the process of scoping/specifying, then expanding scope and specifying again.

Given the relatively small sizes of the workgroups, its recommended that they operate on a consensus basis, with the workgroup lead making reasoned and transparent decisions in the exception case where there is not a prevailing consensus. This demands that there are clear, documented decision points, discussion, and rationale, especially when making decisions for the short term that are known to be trading-off or deferring longer term issues that will need to be revisited. It also demands that workgroup members remain flexible and help the workgroup lead to keep an eye on both the short term pragmatic goals and the long term objectives.

What are the phases of specification development?

Each topic area on the community wiki has a designated topic lead who guides the specification through a four step process:

• Scoping: Scenarios are proposed, documented, and prioritized. Decisions are made on which scenarios and technical objectives will be tackled in this version of a specification.
• Draft: Strawman spec proposals are surfaced, and interested parties comment on and contribute to a proposed Specification through a series of drafts.
• Convergence: There is sufficient consensus that a draft warrants consideration as a final Specification. The broader community is invited to review and comment on the draft Specification. Implementations and prototypes are initiated and the draft Specification is refined. Additionally, the final list of contributors is documented and formal documentation of the contributor patent covenant statements is gathered and published as part of the Specification.
• Finalization: The Specification is put under tight control while final polish and detailed editing is completed. Additionally, implementation feedback is sought out and any identified errors or unclear language is corrected. It is recommended that each workgroup document its finalization criteria. This criteria should include implementation reports (e.g. CmImplementationReports), resolution of issues and potential ways for implementations to do validation (endorse a test suite, e.g. Eclipse Lyo). Once the version of the final Specification is deemed complete, it is called a final Specification and the wiki pages for the Specification are locked to prevent further editing.

Additionally, a non-finalized Specification may be marked Deprecated If there is consensus within the workgroup that specification should no longer be developed and implementations are not encouraged. It is recommended that the workgroup clearly mark this specification as such and indicate a possible way forward, if one exists. This can happen if the specification has not been kept current with OSLC Core specification guidelines, then such a Specification can left this state and not be further developed. Moving to this state can happen from any phase in the Specification lifecycle.

It is conceivable (even likely) that new versions of specifications will be proposed as new ideas or new uses for the resources are revealed or if the scope of a given topic is expanded. Based on the interest of members of the community, it is also conceivable that specifications may be included as part of future proposals to formal standards bodies. The standards process is beyond the scope of open-services.net; the focus of the site is on the earlier stages of community discovery and authoring of common specifications.

How do workgroups involve those who cannot attend telecon meetings?

Workgroups should strive to do all of their work on their mailing lists or the community wiki provided at open-services.net. All decisions should be discussed and made on the mailing lists where all can participate.

Workgroups use regularly scheduled meetings to have additional discussions, review proposals and share news, but decisions should not be made during such meetings. If meeting attendees feel that a decision should be made, they should recommend that decision to the mailing list, summarize the arguments, find consensus via discussion there.

Meeting agendas should be published and noted on the workgroup mailing list two days in advance of meetings and detailed meeting minutes and
recommended decisions should be posted by the day after. Each recommended decision should be stated in its own email so that it can have its own thread of discussion.

How are topics that are not workgroup or domain specific get addressed? How is consistency maintained across the specification efforts of many workgroups?

The OSLC Core workgroup plays an important role in addressing cross-domain topics and in ensuring consistency across domain specifications. Generally, the Core Workgroup is made up of the leads of the domain workgroups, however any OSLC community member may join the Core workgroup. The leads play a dual role with respect to the Core -- they represent the needs and interests of their domain workgroup and help to identify and shape cross-domain specifications and guidance documents (a.k.a the OSLC Core). Additionally, they ensure that relevant OSLC Core specifications and guidance documents are considered and adopted by the workgroups.

Best Practices of Successful Workgroups

Sometimes the simple things can make all the difference. Here are some tips that have proven useful in the operation of OSLC workgroups.

• Getting started - after agreement that a new workgroup is to be formed, the workgroup lead can:
  • Create an initial presence on the OSLC wiki that outlines the intended workgroup scope and objectives (e.g. RmHome)
  • Introduce the topic to the OSLC mailing list and announce a call for participation (e.g. Architecture Mgmt post). Send an e-mail to friends and colleagues about the workgroup and ask them to pass it on to others. Include an initial date for a workgroup kickoff call, allowing 30 days for people to learn about OSLC and the workgroup. Offer to meet 1-on-1 with potentially interested parties to get their ideas and to encourage participation. Use the talents of other active OSLC members to share experiences on how things work with prospective participants.
  • Encourage members to register on the OSLC wiki and subscribe to the mailing list. Include the WikiNames of participants on your workgroup wiki topic.
  • Hold a one hour kickoff call for the workgroup with an agenda that includes:
    • Introductions of members and their motivation for joining in
    • Discussion of the workgroup scope and objectives, OSLC guiding principles, and basic operating procedures
    • Exploration of possible scenarios that might be included, or examples of those that might be out of scope
    • Existing/related industry specifications or standards to consider or keep in mind
    • OSLC terms that govern contribution and IP covenants
    • Frequency and timing for regular workgroup calls
    • Parting action - ask for volunteers to brainstorm and capture high-interest scenarios on the wiki. Use these as a future discussion point in recognizing the range of possibilities and in deciding the subset of scenarios that will be the focus of the coming spec iteration.
• Establish a predictable workgroup meeting schedule and time, (e.g. every other Wednesday at 11:00 ET.) One hour calls twice a month seems to be settling out as a norm.
  • Publish meeting agendas on the wiki ahead of time and capture minutes on the wiki, including participants in attendance, topics covered, important comments and discussions, and to-dos. Make this a practice for all workgroup calls.
  • Poll workgroup members for their availability. Recognize the geographic location of each participant and try to select time that is reasonable for everyone. Consider a rotating start time if necessary.
  • Send out calendar invitations rather than relying simply on e-mail. Many people are simply calendar driven!
  • Use webconferencing and the wiki to guide the meeting and discussion
• After the dust has settled from the kickoff, set a milestone plan.This may be quite high level at the start, but its helpful to set some goals for completion of a full spec iteration. Four to six month cycles is typical. These kind of short cycles help to manage scope and keep things practical. Discuss and consider the timing of potential service provider and consumer implementations. Consider setting milestones for:
  • Completing the authoring and selection of scenarios
  • Proposing an initial specification draft
  • Completion of substantive contributions to the specification
  • The start of specification convergence, final editing, and IP covenant gathering
  • Specification completion
  • Anticipated service provider and consumer implementations

Comments

Send your comments to Core mailing list.