[rfc] website improvements

[Andrew Cowie]

On Tue, 2008-01-08 at 13:05 +1100, Martin Pool wrote:
> We talked late last year about some things that could be improved in
> the Bazaar web site...

>  * A clearer separation of "wiki-type" content (that may be a draft or
> out of date) from the main project pages, which ought to look coherent
> and finished.

This is pretty critical, in my view. Wikis are wonderful, but are not
suited to creating polished content, require you to be online to use
them, and force you to use a web-app to edit them. Yuck.

Meanwhile, you ladies and gents just happen to have a version control
system at your beck an call. Kinda makes sense to be _using_ it to
manage your content :) but that implies that the content be driven from
a text based source.

To that end the solution I've come across is using "Markdown"; I first
started using it for my blog and now use it for rendering the text docs
in the java-gnome project (it is now at the point that whenever I have
to write actual HTML my mind yammers and rebels, heh).

I wrote about Markdown syntax and usage here:
http://java-gnome.sourceforge.net/4.0/doc/style/MARKUP.html
A tiny PHP script is wrapping the single line call to the rendering
engine and that's it, done.

We actually have the java-gnome's website code in the web/public/
directory of our bzr tree, so anyone with a branch has a copy of the
website and can submit changes to the site using the same path as
submitting a patch to the project, ie bzr branch, code, bzr commit, bzr
send.

The markup language used is less significant (though I do quite
enthusiastically recommend Markdown) than the basic technique of having
your website source code be maintained either in parallel with, or as a
part of, the project itself, and then published either automatically on
merge by your bot, or by someone with rights via rsync+ssh.

We recommended this simple approach to website content to one of our
clients, the National Archives in Australia's Digital Preservation
group, and they used it quite successfully for the website promoting
their archiving normalization tool, XENA, see
http://xena.sourceforge.net/ .  Of considerable note in their case was
that they had been trying to use the "documentation" features of
SourceForge, which were a disaster for them and this brought the content
back under their control.

AfC
Sydney

-- 
Andrew Frederick Cowie

We are an operations engineering consultancy focusing on strategy,
organizational architecture, systems review, and change management
procedures: enabling successful use of open source in mission
critical enterprises, worldwide.

http://www.operationaldynamics.com/

Sydney   New York   Toronto   London
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
Url : https://lists.ubuntu.com/archives/bazaar/attachments/20080108/ebf12ac2/attachment.pgp