launchpad-dev team mailing list archive

[James Westby <jw+debian@xxxxxxxxxxxxxxx>]

On Thu, 11 Feb 2010 12:31:27 +1000, Ian Clatworthy <ian.clatworthy@xxxxxxxxxxxxx> wrote:
> Also, one "trick" that's appropriate now and then is to write documents
> that have ongoing value (e.g. end user documentation) instead of
> documents that become obsolete.

Indeed, I like combining specs and documentation, but I don't do enough
of it. You do the UI design by writing the documentation for the feature
despite it not existing, and where you would put a screenshot you put a
mockup. You can then add another page that explains more about what is
going on under the hood, which can act as your architectural
specification for the feature.

This means that you get the benefits of a specification, but it keeps
its value after the implementation is done, and doesn't grow out of date
like a spec will as you keep the documentation up to date as things
change over their lifetime. It also includes a user experience focused
approach as it forces you to think about how people will use it first,
and the goal of a simple to describe interface nicely meshes with your
desire to write less documentation.

There are clearly some problems though, it adds a fairly large amount to
the cost of changing direction in the middle of implementation, good
documentation doesn't always match up with what you need to think about
when designing something, we don't all make great documenters, and
rolling out a half-finished feature becomes trickier as you have to edit
the documentation so people don't get confused.

Thanks,

James