Difference between revisions of "Spec Template"

Revision as of 19:13, 6 August 2008

To claim a project that needs specs written, enter your Bugzilla email address on the ticket, next to the "needs-spec:?" flag. This will let others know that you're working on it. Once you've done that, the basic format for the spec should look like this.

Each individual project may have different requirements for its spec; for some projects, there are special considerations that should be highlighted separately, for instance, or some of these sections might not apply to certain projects. Use your best judgement.

Title of Project

The spec should begin with the title of the project: a few-word description of what the project is intended to do. This can either be taken from the Bugzilla task that created the project, or (if you're working on a spec for a project that hasn't made it into Bugzilla yet, or the Bugzilla task subject line is unwieldy) something you make up. Bonus points for coming up with a snappy title (though the snappy title should ideally also convey what the project's about, so nothing like "Project Heliotrope" or whatever): for instance, "Splitting "Friend" into "Watch" vs. "Trust" becomes "Project WTF", for "Watch/Trust/Friend".

Goal

The one-or-two sentence summary: why we think it should be done, and what it will look like when it's finished, in as brief and succinct a fashion as possible.

Background

The detailed analysis of the problem that the project is attempting to solve, and/or a complete list of motivations, rationale, and any supporting arguments necessary. This can be anything from a few lines to a page or two, and it should be enough information for someone who doesn't follow development discussion to be able to reasonably understand what the project covers, why we want to do it, why we think it's important, what factors we're taking into consideration, etc.

Generally, this will be weighted more towards end-user reasons (ie, the benefit it will have to the end user and to the service/to the codebase as a whole). For projects that are mostly backend, however, it may be more technical. Still, ideally this section will be understandable by the majority of the people who read it, with little to no specialized knowledge necessary.

Skillsets

The necessary skillsets that fully completing the project will require; will probably be several of the following (or others as applicable):

• Backend engineering
• Frontend engineering
• Human interface design
• Graphic design
• Scalability architecting
• Business design

If you don't know how to evaluate what components a project will require, don't worry; leave this section blank, and someone will fill it in for you as the spec goes through further iteration and breakdown.

Requirements

The exact breakdown of what the project should consist of. This should be done in bullet points or short paragraphs, broken down into four categories:

• Must: These are the things that the project must include. Without these elements, the project will be crippled or useless, and shouldn't be released, even in a beta/testing version.
• Should: These are the things that should be included before the project can be considered reasonably complete; with these included, the project can be considered "done" in its initial iteration, and can be provided to the userbase at large with reasonable expectation that 80% or so of people will find it at least a minimal enhancement to their use of the site.
• Could: These are the things that aren't necessary for the project to be considered complete, but which would be useful extensions to the core functionality of the project. Launching the feature/change without these items included wouldn't be a major loss, and many of them may wind up being deferred as future enhancements, but if they're easy and cheap to implement, the engineer working on them should try to fit them in (within time constraints). They should mostly be enhancements or refinements of the "must"s and "should"s, and should connect to those in some way, rather than being completely new sections or subsets of the feature.
• Would Be Nice: The "I want a sparkly pony" section of the spec, containing everything that would be totally awesome with awesomesauce to have, but isn't in any way necessary. These are generally second-level enhancements, major functionality on top of the major functionality changes already listed, things that are intended to make the feature more usable or more desireable to very narrow subsets of specific use cases that aren't very common, or things that go well above and beyond the scope of the spec and are included mostly for completeness. There should be no expectation that the engineer implementing the spec will get to any of the items on this list, much less all, for the initial implementation, but again, if they're easy and cheap, they might make it in.

Potential Problems

Things to keep in mind when implementing the spec:

• potential social complications that should be kept in the forefront of the mind when making implementation choices
• any human interaction troublespots (things that people might find hard to use, non-intuitive, etc)
• aspects of the project or feature that might upset people or break certain site-usage patterns and ideas for how to implement the feature without tripping those concerns
• any potential technical issues that should be considered when implementing
• anything else (technical, design, or social) that you think the engineer should consider

Again, if you don't have the technical experience with the DW codebase necessary to know what the potential technical issues might be, don't sweat it; you can leave those bits out of the spec. (We'd rather you did, in fact, instead of guessing.) Still, if you can think of anything that might be a problem down the road, technical or social, this is where you can put it.

Other Sections (as applicable)

The spot for any project-specific elements that don't fit anywhere else in the spec.

If you run into questions at any point, want to get opinions from other people, want some more background on the history or motivation of what a project's intended to do, or want an explanation of what a Bugzilla project ticket's shorthand description entails (since Denise tends to the extreme shorthand when writing these things up in Bugzilla tickets), feel free to bring discussion to the dw-discuss mailing list. (After launch, we'll have an on-site area for discussion of these things, but for now, the mailing list will do.)

Once you have the spec to a point where you think it's ready for review by a DW site admin, upload the spec as an attachment to the Bugzilla ticket. A project admin will review your spec, make suggestions, work with you to make enhancements, and eventually accept the spec.