Development

It is in this Development Phase that the Working Group develops the Technical documents. Please take a look at the diagram Specification Development Steps below.

Specification Development Steps

Type of Documents

Type of documents developed during this phase: (this list is not exhaustive)

Independent of the document type, the Working Group should develop the above documents following the process described in the Tasks section. It is an iterative process that starts when the template baseline is uploaded to the repo and ends when the Working Group finally agrees with the document before sending it for Ratification.

Each of these documents is based on a template. You can find a suitable template document in enabler_template_repo . To obtain more information on Standards Documents, visit Documentation

Whitepapers

In Standards Development Organizations, SDOs, a Whitepaper is an informational document issued by the Organization to promote or highlight the features of a Technical solution, product, or service that it offers or plans to offer.

After completing the Technical Specifications, the final step is to create and execute activities that communicate the product, brand, or service to the end user. Ideally, the Organization should build a community to make people aware, attract and induce to use the product or service designed by the Organization.

Use Cases & Requirements

A Use Case describes how users interact with a system or product.
The Use Cases normally are listed on the appendix of the Requirements document, (RD).
The Requirements Document (RD) contains one or more Use Case(s) and describes the characteristics of a proposed system from the viewpoint of the system's End User. It describes Business Requirements rather than Technical Requirements.
The Working Group SHOULD dedicate 10% to 20% to build the Use Case and Requirements document out of the total effort to create a Technical Specification.
The Working Group SHOULD define a milestone date - RD Approval Date - as reference by when the Working Group should complete the RD document.
The RD Approval Date SHOULD be added to the Release Planning table.

Architecture

The Architecture Document (AD), contains an Architectural Model of the system to build. The model identifies the project's internal functional components and all the communication relationships between components inside or outside the project. Sometimes, the AD document is a section inside the Technical Specifications document.
The Architecture diagram MUST contain components, end-points, or interfaces, and what is in and out of scope.

Technical Specifications

The Technical Specifications document (TS) often refers to a set of documented technical requirements to be satisfied by a design, protocol, application, product, or service.

Supporting Material

Some Technical Specifications define schemas, profile data documents, code scripts, etc. In these cases, creating JSON, XML, YML, etc., files is a good practice to keep the content outside the TS.

Test Cases

The Enabler Validation Plan (EVP) is a document that contains the criteria and outcome(s) required for successful validation.
The Enabler Test Specifications (ETS) document contains an end-to-end delivery focus and addresses conformance and interoperability testing using service end-points and infrastructure components.

Tasks

The image below depicts a sequential list of tasks. At the top of the image, you can see the color and the Working Group Role responsible for the task.

Development Tasks

Pull Request Against Baseline

Working Groups SHOULD define a CONTRIBUTING.md document for each repository where Group is developing Technical Specifications.
The CONTRIBUTING.md document indicates how to contribute to a particular repository step by step.
Visit this link to create a brand new Pull Request
This other link explains how to update an existing Pull Request

A Pull Request lets you tell others about changes you have submitted to a branch in a repository on GitHub.

Discussion

The Chair of the Working Group MUST ensure that all the members of the Group have a fair opportunity to Review the Pull Requests raised against any baseline document.
The Chair SHOULD assign a maximum discussion time for any Pull Request to Review
- The Chair MAY suggest adding additional discussion time to continue discussing the topic during or in future meetings.
- If the Discussion keeps dragging over several meetings, then the Chair should ask the interested parties to summarize their views in a presentation to the Working Group

Please refer to Chairs Best Practices for recommendations on how to perform Chairs duties.

Review & Approval

Review & Approval is a process used by the Working Group to ensure that every member can voice their views about a particular change or suggestion before merging it into the baseline.
Pull Requests should be available to the Working Group for Review during the period stipulated by the Working Group:
Review & Approval Criteria:
- A Pull Request SHOULD be accepted and merged if it receives at least three "OK's" and no OBJECTIONS.
- If a Pull Request receives COMMENTS it is up to the Editor to decide how to incorporate those COMMENTS
- If a Pull Request receives an OBJECTION, it cannot be merged until the OBJECTION is withdrawn or resolved by the Working Group
OBJECTIONS resolution:
- The Working Group MUST review any OBJECTIONS presented by a member of the Working Group
- If an OBJECTION is discussed and still sustained, then it MUST be resolved by Voting.
The final disposition of a Pull Request is MERGED, or CLOSED.
A Pull Request MAY be CLOSED if the Working Group doesn't unanimously agrees with its content.

In Standards Development Organizations unanimously means that all the members of the Working Group had the chance to voice their view on a particular topic under review. If a Vote on a PR takes place, the outcome of the vote is enforceable and final unless the ballot is appealed .

Merging an Agreed PR

Only Working Group Chairs, ViceChairs and Editors have permission (WRITE access) to merge an Agreed Pull Request.
- Only Agreed Pull Requests PR's that have unanimously met the Review & Approval process can be merged.

Frequent-Asked Questions

Please raise your questions here