WritingGoodSpecifications

Not logged in - Log In / Register

This page needs your help! Can you help ensure the information on this page is accurate? If so, please make the changes directly in the page.

Introduction

This is part of the BlueprintDocumentation which explains to people how to make the most of the feature tracking in Launchpad. It is also written to help new contributors to Ubuntu and other free software projects figure out how most effectively they can get their ideas / features / wishes implemented.

What's a "good" specification?

What makes a good feature specification? The answer is "just enough information to do it right". Of course, that varies hugely depending on what the feature is, what the project is, and who you are. In general, the more people your feature implementation will touch, the more it's worth investing in the discussion of how something will work before you actually get started.

A lot of the benefit of the specification process comes from debate and discussion. Getting feedback from others makes you think about things you otherwise might not have considered - perhaps it even expands your sense of the importance of the feature you had originally conceived, or perhaps it suggests that the feature would be even more useful if it was done slightly differently.

That said, don't get bogged down in planning when the only person who needs to know is yourself. Huge design documents get more and more difficult to keep in touch with reality. Its best to pick smaller pieces of the puzzle, draw up a reasonable plan for one of them, and then implement it rather than trying to define in detail how a huge system will all hang together.

Getting outside expertise

A lot of the people who WANT features won't have the skills to IMPLEMENT them. It's common to have someone popping onto a mailing list or IRC channel and saying "Ubuntu would ROCK if it had feature XYZ!". As soon as they are asked how they would implement that, they disappear. Which is often a pity, because some of those ideas might well have legs if they could get the right set of eyeballs and brains around them.

So use Blueprint as your way of building up a small community of people who have a common interest in the feature you have conceived. You need a mix of people - some of whom have the knowledge to implement the work, and some of whom are the sorts of people who can rally support for an idea. Building community consensus is often harder than actually developing the code! And of course, it's great if you can find people with a talent for making things LOOK GOOD (artists and user interface guys) as well as WORK WELL (quality assurance, testers and end-users).

Anybody can subscribe to a feature specification, and the number and quality of subscribers can be a good indicator of the potential interest in the community for a particular feature. If you have a lot of subscribers with good credentials it won't go unnoticed by your project leaders. That said, you SHOULD NOT subscribe someone else to a specification unless they work for you or you have their permission. Subscribing someone to a feature spec means they will get email about it, and they may just not appreciate that, no matter how good your intentions.

Actually writing the specification

Here are some hints for the text of your spec:

What to cover

Your specification should touch on:

Your project probably has a template specification that you can use as a starting point. In the case of Launchpad and Ubuntu we have:

How do you know you are winning?

The project leaders are the people who get to say what the priority of a specification should be. They determine what the project is likely to include in its mainline codebase and what it won't. At the same time, there's plenty of room for dissent and diversity of opinion - some of the very best features are often developed on the side by a small group of people who want them, and then they are incorporated in the mainline only once the project leaders can actually see and test them.

So don't be discouraged if your specification gets a "low" or "not" priority - that just means that the project leaders themselves aren't going to jump onto the problem. It does not mean you shouldn't bother to continue.

Getting a higher priority from the project leaders does generally mean that you might get direct help from one of the core developers or members, so its worth canvassing for support for your feature idea. But don't overdo it - if people aren't excited about your feature, they won't get excited unless you improve the way you are describing it, and that means putting more work into your specification.

WritingGoodSpecifications (last edited 2016-04-12 10:29:43 by wgrant)