launchpad-dev team mailing list archive

[Ian Clatworthy <ian.clatworthy@xxxxxxxxxxxxx>]

On 31/03/10 19:59, Bjorn Tillenius wrote:
> Hi guys,
>
> so, it's time for the Technical Architect team to tackle its first task.
> Create the Launchpad Architectural Vision.
>
> First of all, what is it? It's aimed to be documents that describe the
> different parts of Launchpad. It will explain how Launchpad works, which
> moving parts are involved, and how it will fit together. It will also
> explain the various sub-systems, and explain how to do various things in
> Launchpad code.

> These are the things I thought of so far that should be included:

> Anything missing?

Hi Bjorn,

As a high level framework, I'd like to strongly recommend using the 
Viewpoints and Perspectives approach outlined in Software Systems 
Architecture. See http://www.viewpointsandperspectives.com/ and, more 
importantly, buy the book. It's truly excellent.

> A couple of things to think about:
>
>      * I don't want to give too many guidelines how to write. Let's do a
>        set-based design, look at how different people format their
>        documentations, and consilidate later

This may work out well and it may not. A huge part of being a good 
architect IMO is communicating clearly to the wide variety of 
stakeholders. I suspect you'll be more successful if you start from a 
good set of documents each with a good table of contents (vs letting 
everyone create their own).

It's therefore wise IMO to start from a set of documents, each one of 
which has a clear target audience. The Vision document you've outlined 
sounds a look like the "Development Viewpoint" articulated by Rozanski & 
Woods. It's primary audience is developers. It's recommended content is:

* the system’s module organisation,e.g. the key layers and packages
  within each

* common processing that all modules must implement, e.g:
  - initialisation
  - termination and restart
  - message logging and instrumentation
  - I18N
  - third-party libraries
  - processing of configuration parameters
  - security
  - transaction management
  - db interaction

* any required standardisation of design, coding and testing, e.g.
  patterns to use to handle locking or model-view interaction

* the organisation of the system’s branches.

Other viewpoints target other audiences, e.g. the Operational viewpoint 
helps system administrators and developers understand things like:

* the installation model
* the migration model, covering functional migration, data migration
  and backout strategies
* performance monitoring
* configuration management (or web server and db parameters)
* backups and restoration
* etc.

A high level outline of the 6 viewpoints is given here: 
http://www.viewpoints-and-perspectives.info/index.php?page=vp-intro

>      * Please use doctests! It's important that the documentation is
>        up to date. Doctests is a great way of doing this. The doctests
>        shouldn't aim to test the feature, though. We have other tests for
>        this. The aim for the doctest is to show examples, and to help
>        keeping the documentation up to date. Running the doctests isn't
>        hooked up yet, but I'll work on it next.

This blog post explains how Doug Hellmann puts together "Python Module 
of the Week" using Sphinx, Paver and Cog: 
http://blog.doughellmann.com/2009/02/writing-technical-documentation-with.html

You may want to reuse some of his scripts to validate that code examples 
actually work as advertised.

>      * Documentation for Sphinx can be found at
>        http://sphinx.pocoo.org/contents.html

+1 on using Sphinx. We use for the vast majority of Bazaar documentation 
now and it's working well for us.

Ian C.