Firefox 3: Feature Plan Templates
Mike Beltzner
Y'all,
In order to make sure that we're scoping work appropriately and not
leaving ourselves exposed to nasty surprises near ship-time, I've
taken a whack at updating the Feature Plan Template to be used by
contributors working on features* for Firefox 3. The idea is that
every feature would have a document based on this template. This
template aims to create a Feature Plan document that would act as:
* document of record for feature overview, tracking and status
* primary design document for the feature w/links to related plans
& documents
* document of record for "cross-cutting" PRD requirements
* on-ramp for contributors looking to get involved
It lives here: http://wiki.mozilla.org/Firefox3/Feature_Plan_Template
I'd appreciate your comments and feedback, specifically regarding:
* is this document too heavy or cumbersome?
* is there important information missing from this document?
* how else could the document be made more useful?
* are there other static reference documents (ie: accessibility
guidelines?) we should be linking to?
cheers,
mike
Benjamin Smedberg
> (follow-up to dev.planning, please)
>
> Y'all,
>
> In order to make sure that we're scoping work appropriately and not
> leaving ourselves exposed to nasty surprises near ship-time, I've taken
> a whack at updating the Feature Plan Template to be used by contributors
> working on features* for Firefox 3. The idea is that every feature would
> have a document based on this template. This template aims to create a
> Feature Plan document that would act as:
>
> * document of record for feature overview, tracking and status
> * primary design document for the feature w/links to related plans &
> documents
> * document of record for "cross-cutting" PRD requirements
> * on-ramp for contributors looking to get involved
>
> It lives here: http://wiki.mozilla.org/Firefox3/Feature_Plan_Template
>
> I'd appreciate your comments and feedback, specifically regarding:
>
> * is this document too heavy or cumbersome?
I'm not sure what 'API changes' is for. It's often hard to know up front
what API changes are going to be required for a feature. Is there a
particular reason we need to track this?
> * is there important information missing from this document?
At the Firefox summit, we brainstormed a checklist for new features. This
list looks a lot like that list, but there are a few things left off. Do you
remember who wrote that list down? (I think it was schrep.)
Off the top of my head, I can remember:
* website integration: how will this feature interact with mozilla or
non-mozilla websites, scalably and reliably
* profile data: does this feature introduce new data formats in the profile,
and have they been designed for forwards/backwards compatibility
* testability: this might fall under your "reliability/stability" heading
If this checklist is not that checklist, we should definitely complete that
checklist for each feature as well.
--BDS
Deb Richardson
Is the template to be used to create "documents of record" that are then locked and managed through a strict change management process, referred back to by the working documents that track status and such, or are these the working documents themselves that will change continually as the features are developed?
~ deb
Mike Beltzner
> Is the template to be used to create "documents of record" that are
> then locked and managed through a strict change management process,
> referred back to by the working documents that track status and
> such, or are these the working documents themselves that will
> change continually as the features are developed?
The latter.
I might, in fact, be misusing documents of record here. They're meant
to be living documents that are modified as required by the
implementation team in order to fulfill the requirements set out by
the PRD (which are managed through a change management process).
They're also meant to be places where we can send interested parties
who are wondering "so, what will <feature-name-here> look like?" or
"hey, what's the l10n impact of <feature-name-here>", etc.
Subgoals include: ensuring that this design is scoped & done up-
front, providing a historical record of those design documents, and
allowing interested parties to see how <feature-name-here> is doing
something in order to re-use ideas, etc.
Now, there's an argument to be made for "this sort of documentation
is hard to keep in sync with the code," and I feel that pain. That's
why I want to try to make the template both lightweight and useful
enough that it's not felt to be cumbersome, and indeed, such that
anyone who notices a discrepancy can go and update the page.
cheers,
mike
Mike Beltzner
I think initially it would be useful to plan out what APIs will need
to be modified, so that as all teams are doing this we can start
looking for overlap/areas for wider refactoring as required. Then, as
we come up to the close of the product cycle, I was thinking it would
be useful for DevMo and extension developers to see what APIs have
changed and how that might affect their software that's built on top
of those APIs. This might be naive thinking of me, though, so feel
free to tell me I'm wrong! :)
>> * is there important information missing from this document?
>
> At the Firefox summit, we brainstormed a checklist for new
> features. This
> list looks a lot like that list, but there are a few things left
> off. Do you
> remember who wrote that list down? (I think it was schrep.)
>
> Off the top of my head, I can remember:
>
> * website integration: how will this feature interact with mozilla or
> non-mozilla websites, scalably and reliably
I think this fits into "Web Compatibility", but I'm not sure. Do you
mean specific features that have dependencies on some web page/
service being present, like the "Report a Web Forgery..." menuItem in
Firefox2? If so, yeah, that section is missing. Maybe a
"dependencies" section?
> * profile data: does this feature introduce new data formats in the
> profile,
> and have they been designed for forwards/backwards compatibility
Good call. We should list out things like:
- where client data is stored (and how it's cleared)
- what new prefs are created by the feature
- profile migration
> * testability: this might fall under your "reliability/stability"
> heading
I was hoping that this would be covered in the "Test Plan" document
that the template implies should exist for every feature. Tim/QA folk
will hopefully help build out a template for that document.
> If this checklist is not that checklist, we should definitely
> complete that
> checklist for each feature as well.
It's not, so we should. Is that documented anywhere? I don't know if
I was at that breakout at the summit ...
cheers,
mike
Basil Hashem
>> If this checklist is not that checklist, we should definitely
>> complete that
>> checklist for each feature as well.
>
> It's not, so we should. Is that documented anywhere? I don't know
> if I was at that breakout at the summit ...
I wasn't at the summit breakout for that session but I tried to
capture some of my discussion with Schrep on this topic as part of
the "cross-cutting concerns" of the PRD @ http://wiki.mozilla.org/
Firefox3/Firefox_Requirements#Cross-Cutting_Concerns_.
26_Fundamentals. At yesterday's Firefox team meeting, Justin Dolske
brought up the fact that Sun Microsystems has a checklist as well.
Justin, can you please post any items missing from our lists?
Thanks.
--
Basil Hashem
ba...@mozilla.com
Axel Hecht
Some aspect of this goes together with missing pieces in the Global
audience section of Basil's doc,
http://wiki.mozilla.org/Firefox3/Firefox_Requirements#Global_audience
I'd mention
- which site should we integrate to?
- do we have permission to do so?
- what happens if that permission is revoked?
and on a more technical level
- what's the estimated load on a site? How often does that feature try
to get which data.
- Does it lower traffic demands when the site goes down (like feeds don't)
Those are the ones I have at the top of my head right now.
Axel
Benjamin Smedberg
> I think initially it would be useful to plan out what APIs will need to
> be modified, so that as all teams are doing this we can start looking
> for overlap/areas for wider refactoring as required. Then, as we come up
> to the close of the product cycle, I was thinking it would be useful for
> DevMo and extension developers to see what APIs have changed and how
> that might affect their software that's built on top of those APIs. This
> might be naive thinking of me, though, so feel free to tell me I'm
> wrong! :)
As for initial design, it would be good to have links to API design
documents (which will need to be separate, obviously). But that won't
involve all the APIs touched, just the fundamental ones for a feature. So
perhaps instead of "any API changes", it should be "major new or changed APIs".
>> * website integration: how will this feature interact with mozilla or
>> non-mozilla websites, scalably and reliably
>
> I think this fits into "Web Compatibility", but I'm not sure. Do you
> mean specific features that have dependencies on some web page/service
> being present, like the "Report a Web Forgery..." menuItem in Firefox2?
> If so, yeah, that section is missing. Maybe a "dependencies" section?
Yes, I am concerned about dependencies on *specific* websites (AMO, report a
forgery, etc).
--BDS
Robert Sayre
>
> * is this document too heavy or cumbersome?
I think so, in the Design and Implementation section.
> * is there important information missing from this document?
> * how else could the document be made more useful?
Most of that section should be generated from IDL / JS comments,
and the test section should be links to unit tests in lxr. If there is a
need for a separate section on manual test planning, ok.
-Rob
Axel Hecht
AFAICT, these documents should be create before the feature, not after
the fact.
It's more a "You can reuse most of you write here for comments in the
interfaces" rather than the other way around.
IMHO.
Axel
Mike Beltzner
> Mike Beltzner wrote:
>> * is this document too heavy or cumbersome?
>
> I think so, in the Design and Implementation section.
What, in particular? I'd like to see some stab at UI design up-front
(even if it's just getting it down there so people can start
imagining and commenting on the interactions) but I'm a little biased
there, and some of these features will be pretty UI-less.
The architecture document is the one which I could see as being "too
heavy", though I was picturing something that could be written up as
an overview with links to appropriate code files. Maybe labeling that
section "documentation" as opposed to "overview" or "10,000ft view"
is making it look heavier than it needs to be?
>> * is there important information missing from this document?
>> * how else could the document be made more useful?
>
> Most of that section should be generated from IDL / JS comments,
> and the test section should be links to unit tests in lxr. If there
> is a need for a separate section on manual test planning, ok.
As Axel said, once done, I'd totally support replacing those sections
(or just linking), but I think in the getting started phase, there
should be some indication that thought has been given to what sort of
tests need to be generated, what sort of architecture is being built,
etc.
cheers,
mike
Myk Melez
> At the Firefox summit, we brainstormed a checklist for new features. This
> list looks a lot like that list, but there are a few things left off.
> If this checklist is not that checklist, we should definitely complete that
> checklist for each feature as well.
If the lists look a lot alike, it'd be better to merge them than to make
folks fill out two separate pieces of paperwork.
-myk
Myk Melez
> I've taken
> a whack at updating the Feature Plan Template to be used by contributors
> working on features* for Firefox 3.
...
> I'd appreciate your comments and feedback
The overall idea of having such a document for each major feature
(including ones that have already landed) appeals to me, as long as we
remain flexible about which parts of the document need to be done, and
when they need to be done, for the various features.
But it was hard for me to form an opinion just from looking at the
template, so I decided to try it out with the Site-Specific Preferences
feature I've been working on.
Here's my very rough initial draft:
http://wiki.mozilla.org/Site-Specific_Preferences
First, I'll note that it took me about four hours of mostly
focused effort to complete the initial draft, which seems like a
reasonable price to pay for the benefits such a document can provide.
And now that I've written it, here are some thoughts on the template:
1. Perhaps this is an issue with the wiki formatting generally, but it's
really hard to tell that Motivation, Use Cases, Requirements, and
Schedule are subsections of the Overview section. I was going to say
that the Overview and Motivation sections seem to overlap significantly
until I realized that one was just a part of the other.
Further confusing matters is the fact that the Design & Implementation
section has two kinds of content: the Documentation and Repository
chunks, which are specified via semicolon-prefixed titles, and the API
Changes, Extensibility, etc. subsections, which are specified via
next-level equals signs.
I understand that the intent is for the content chunks to provide
information (or links) about the design and implementation as a whole,
while the subsections provide information specific to the cross-cutting
concerns. And that the reason the cross-cutting concerns are in there
is because the information in them pertains to design and implementation.
But I think the whole cross-cutting concerns as part of D&I is a bit too
implicit, and the template strongly suggests that D&I details should be
in separate pages, which may not make sense for some features (sometimes
features will be small enough for that stuff to be inline, while in
other cases that stuff will be in separate pages but not pages on the
wiki that are subpages of this page).
So I'd say that it probably makes more sense to break this into two
top-level sections--Design & Implementation and Cross-Cutting
Concerns--and instruct authors to put details into D&I while providing
more general information (along with references to the aforementioned
details) in the CCC subsections.
2. it would be useful for references to "use cases", "functional
and non-functional requirements", and the like to be accompanied by
definitions of those terms (or links to pages that define them). After
all, these docs will be written by engineers in many cases, and I for
one don't have an expert understanding of those terms, although I
generally understand what they mean.
For example, you might describe "use cases" as "examples of how users
might use this feature" and link to the wikipedia article on the subject
<http://en.wikipedia.org/wiki/Use_case>.
3. I didn't know what to do with the Discussion & Implications section
by the time I reached it. But perhaps that was just because my brain
was fried by then from all the writing and editing.
Otherwise, the template seems reasonable and useful.
-myk
Mike Beltzner
> And now that I've written it, here are some thoughts on the template:
<snip>
Thanks for this great feedback, Myk, which is basically useful in its
entirety, and I'm pretty much gonna take all your suggestions. I hope
to have time to rev the template by the Fx3 meeting tomorrow, but I'm
moving and will be without internet for a large part of the day, so
it'll be a bit of a race!
cheers,
mike