Implementation section of specs

[Paul Dufresne]

While some nice comment have been made on how to make good quality spec
(for the mouseTweaks spec I did not look yet), I'd like to share one
compaint I have about how many (if not most) specs treat the
implementation
section.

My problem is that specifications have no section in which they say how
the implementation is advancing or going. I know Launchpad have a field
indicating progression, but there is no way to know which parts of the
design have
been implemented yet and which don't.

In fact as I read this, I come to the conclusion that my complaint seems
to
be a bug in https://wiki.ubuntu.com/SpecTemplate itself.
In https://wiki.ubuntu.com/SpecSpec, it is a bit unclear if
"Implementation Plan"
is a different section than "Implementation". 

As I read and understand it, they should be separated sections, the
"Implementation" section
being edited by the assignee as it implements it, first saying what is
implemented or not,
and when implementation is finished, only a note saying it has been
fully implemented should
stay, with information with what is different than the design.

I think what most people, and the Template for now, is using the
"Implementation" section, should be "Implementation
Plan". In fact SpecSpec say that "Implementation Plan" should contains:
"This section is usually broken down into subsections, such as the
packages being affected, data and system migration where necessary, user
interface requirements and pictures (photographs of drawings on paper
work well).". Clearly way too much to also serve to show what is the
progress of the implementation.

So to summarize, I propose to edit SpecTemplate, to contains no
"Implementation" section, and to add these two sections:
"Implementation Plan" and "Implementation Progress". This should make it
more probable to be used correctly by a new
spec writer.

-- 
http://www.fastmail.fm - Or how I learned to stop worrying and
                          love email again