Specification
[…] on any non-trivial project (more than about 1 week of coding or more than one programmer), if you don’t have a spec, you will always spend more time and create lower quality code. ~ Joel Spolsky
A specification is an efficient way to communicate your work with others and ensure that you have consensus on the design before progressing with its implementation.
- Expected duration
- 2 hours per team member
- Deadline
- 2359 on Lessons 11, 22, 31
- Points
- 25 points
Assignment
Each team is responsible for collaborating on a single specification. Completing the specification early in the sprint (e.g., by the conclusion of the first week) is recommended to minimize the amount of rework required if substantial changes are requested. After its initial submission, each specification should be reviewed and (eventually) approved by others on the team, looking for areas of ambiguity, incompleteness, inconsistency, etc. Implicitly this means that 1-2 team members should draft the initial version of the specification and further development of the specification is handled through comments on a pull request. Following this review and any required changes, the specification serves as a “contract” for what will be implemented. Later changes must be approved as part of the requirements management process.
When you write the specification, exhaustive detail is not necessary, but someone else should be able to implement the feature if required.
You must use the provided template for the specification. Add your
specification to the repository’s docs/specs directory. The specification
should be written using reStructuredText
(RST), which is a lightweight markup
language for text documents. The file name for your specification should
describe your work and use dashes between words. For example, if adding support
for single sign-on using OAuth, the file name for your specification might be
add-oauth-support.rst, or if refactoring existing back-end code, the file
name might be refactor-database-interface.rst.
The specification template is derived from those used by OpenStack. As an open source project, the quality of OpenStack’s specifications varies, but those of the compute service are generally well-written. If struggling to understand what amount of detail to include in the specification, one approach is to review a half-dozen or so OpenStack specifications to get a feel for what is required to manage a large open source project. (Hint: More information is generally better, and although exhaustive detail is neither required nor appropriate, always trend toward including more information whenever in doubt.) A more entertaining resource is Joel Spolsky’s series “Painless Functional Specifications,” which addresses this topic humorously and pragmatically.
Use the template in the project repository for the specification.
Submission
To “submit” your specification, create a pull request in GitHub.
The pull request triggers a review of the specification so that you have feedback and the opportunity to improve the specification, ideally before you complete substantial work on the implementation. Expect to iterate on the specification, using the feedback to improve the initial version – it’s rare for any software engineering artifact to be “right” the first time.
Grading
The specification will be graded at the end of the sprint and is based on its final version (i.e., incorporating all updates from the review process). If the pull request has been merged, then you will earn full credit for the specification. Conversely, a pull request with unaddressed comments will earn a low score because there are remaining opportunities for improvement.
Your goal should be to address the feedback as thoroughly and as quickly as possible to ensure that the specification is approved and earns full credit for this assignment. Take advantage of the iterative review process – the quality bar is high precisely because that’s what expected in real software projects.
Rubric
The following grading rubric will be used for this assignment:
- Superb (100%)
- Pull request(s) approved / merged
- Proficient (90%)
- Trivial issues (e.g., formatting and clarification to wording), but no content changes required
- Competent (75%)
- Minor issue that requires partial revision of one section
- Marginal (50%)
- Major issue that requires complete revision of one section or multiple minor issues that require partial revision of multiple sections
- Unsatisfactory (25%)
- Multiple major issues that require complete revision of multiple sections