Writing Linaro Requirements

This page guides the process of writing up requirements for submission to Linaro's roadmap plan.

Quick Links:

Principles

example requirement

The requirements specification should be a document, written using English sentences, that describes a problem and its proposed requirement. Ideally, the requirement is understandable by people who don't have deep technical knowledge in the subject. To achieve this, you should contextualize the problem within Linaro, describing the component affected and relevant prior work.

A requirement should specify a single body of work; it shouldn't amalgamate different problems together. One place where this amalgamation tends to happen in Linaro is around optimization: the requirement may be calling for an implementation of a certain currently-unsupported feature, with an additional requirement for enhanced optimization tacked on to it. It's better to split that into two requirements, in particular if the feature is something significant, since it is likely that it will be classified as Epic and need to be split up in the process of Acceptance.

Required Fields

The Headline

The headline is a one-line representation of the requirement. Think of the headline as something that we could sensibly include in a report of Linaro achievements.

It should be able to fit into a sentence prefixed with "This quarter Linaro delivered <headline>"; for instance, "Consolidated kernel GPIO interfaces for member boards" or "Initial A15 support in the linux-linaro kernel tree".

The Description

The description should expand on the headline, introducing the problem and contextualizing the work. It often helps to start the description by explaining what is missing or can't be achieved in the absence of the requirement; for instance, "Linaro's images currently offer no support for On-Chip Debugging (OCD)" or "GCC on ARM currently does not use profiling data as input to its code optimization facilities."

The description should identify the software components affected by the requirement; for instance, it should outline if there is support missing in the kernel or some other important package; it should highlight impact on certain parts or aspects of the system; and it should clarify if the requirement explicitly does not cover a certain implementation.

The description can refer to external documents in order to further detail the requirement or any prior work in the area.

The Acceptance Criteria

The Acceptance Criteria (sometimes shortened to just AC) is the most important part of the requirement. It is used to verify whether or not a certain goal has been reached, and in doing so, it binds the work into a concrete result.

Acceptance Criteria should clearly state how we should verify that the requirement is delivered; it should therefore ideally describe it in terms of a Linaro deliverable: a component, image, patch, document or similar artifact. It should highlight the steps to be taken to verify delivery; for Linaro, that usually will start with an artifact, ranging from a code tree (an upstream tree, linux-linaro, landing team kernel trees, etc) to components (a release of linux-linaro, gcc-linaro, glmark2, etc) to whole images (the Ubuntu Desktop image, the Android LEB, etc).

The Acceptance Criteria should describe intended outcomes and behaviours; if there are multiple outcomes they should all be described. If the list is very extensive then an external benchmark, specification or test suite is a good way of ensuring the boundary for delivery is clear; in this case the Acceptance Criteria text should note that the attached document should be used to support the acceptance testing process.

Vague Acceptance Criteria lead to many problems beyond not being able to tell whether the work is delivered; it can cause work being done in the wrong areas, or targeting the wrong deliverables or components, or yet targeting a different level of reliability (for instance, if the deliverable is meant to be verified under battery operation versus AC, or if it is intended as something which can be shipped in a product rather than a protoype).

Attachments

You may include attachments or supporting documents to your requirement slide; these should have the function of clarifying or going into more detail about certain terms described in the requirement. Those attachments will be archived together with the submitted slide.

Attachments shouldn't be used to extend the requirement, or to replace its need -- the requirement slide should stand alone in describing the work at a high level.

internal/archive/Process/Roadmap/Writing (last modified 2013-08-27 23:15:49)