Documentation Strategy

By Linux_Foundation - January 25, 2009 - 1:43pm

Satisfied Requirements
The workgroup will begin by taking the published CGL 4.0 documents and splitting them into two parts. The "[Satisfied Requirements]" document will include all requirements that are fully satisfied by the current mainline kernel and/or latest enterprise distributions. The goal is to have a formal way for the carrier community to communicate to their vendors and the Linux community what requirements they expect to continue to be satisfied over time. This document is not expected to change frequently, except by having new requirements added to it as they are satisfied.

Carrier Gaps
The second, and more dynamic document, is the "Carrier Gaps" document. This document describes carrier requirements that are not currently satisfied by the mainline kernel and/or latest enterprise distros. Each requirement will include one or more specific examples of carrier needs that are not currently being satisfied. These requirements should include some proof-of-concept to avoid blue-sky requirements. Examples of proofs-of-concept are proposed patchsets, the existence in other OSes like Windows or Solaris, or existing products that use different approaches such as a hard RTOS.

Each section of the "Carrier Gaps" document will specify a requirement (what) and the justifications (why), but not the implementation (how). Although proposing a patchset is perhaps the most efficient way of demonstrating a capability, the CGL workgroup does not expect to dictate what patchsets should be accepted. Instead, the goal is to have kernel developers review and comment on these requirements on the CGL mailing list. This initial round of review will hopefully reveal issues that need to be addressed for a patch to be accepted, or at least serve to illustrate the underlying requirement that carriers are aiming to solve. Ultimately, any proposed kernel patches must be posted on LKML and accepted by the relevant subsystem maintainer under the normal kernel development process. The goal of CGL is to increase the early communication between the carrier and Linux communities to increase the probability that functionality needed by carriers and their vendors will be quickly adopted.

The "Carrier Gaps" document is expected to initially (and perhaps always) exist as a wiki page that can be edited by any member of the workgroup, although supervised by a document editor. The aim is to dramatically lower the cycle times between the carrier community requesting functionality and the kernel community and other development communities commenting on the features and/or implementing them. Rather than waiting for a lengthy publishing process, the idea is to use the Carrier Gaps document as a living repository of the status of different projects and the interaction with the kernel community. As functionality is implemented, the section would be moved to the Satisfied Requirements document. Functionality that is likely never to be implemented can, after discussion, be listed in a special section at the bottom to explain the history of the request and the negative response from the kernel community.

While interactions with the kernel community are the initial focus of the workgroup, this format is expected to extend to other upstream communities as well.