[rfc] website improvements

[Aaron Bentley]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Martin Pool wrote:
> We talked late last year about some things that could be improved in
> the Bazaar web site.  I have started implementing some of them.  The
> main things I want to accomplish are:
> 
>  * A site that's easier to maintain - at the moment putting up new
> releases requires making several edits which at best takes a while,
> and at worst may leave some broken links.
>  * A better development news section, also available as an RSS feed.
>  * Tighter text and better presentation.  Removing the wiki toolbar
> bits from the front page.  Making the homepage more concise.

I've been a bit frustrated because it feels like the previous redesign
of the wiki was never completed.  For example, the icons for "updated",
"new" and "deleted" in RecentChanges are distorted and unreadable.

For another, the headings of ReST pages are blue because of poor CSS
coding that causes all contents of an <a> tag to be blue, whether that
tag is a link or an anchor.

>  * 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.
> 
> Some of these points are about content, and some are about mechanism.
> Clearly we can edit the homepage text within the wiki.  And we have in
> the past, and could now, make an effort to remove or clean up outdated
> wiki pages.  But some things, like getting a good user-oriented news
> feed, or a news toolbar, do seem difficult to do within Moin.
> 
> Therefore I want to move the wiki to wiki.bazaar-vcs.org and have a
> main site at bazaar-vcs.org that's generated from templates in a
> Bazaar script.

I think you mean Python script?

> So to either change the text, or to add new items
> (releases, plugins, news) people will commit to the branch, which I
> expect would be writable by anyone in the Bazaar team on Launchpad.
> Andrew Cowie (AfC) advocated this a while ago.

I much prefer the wiki workflow to what you're describing.  The instant
feedback is incredibly useful.  I don't like writing docs nearly as much.

Isn't the whole Ubuntu site basically one wiki?  Can't we make that work
here?  Restrict the rights to Bazaar team, and limit the focus, but I
definitely prefer wiki editing.

Andrew makes the following points:
  "The front side web site can and should be in version control"

It is already in Moin's version control.  I'm also considering writing a
plugin to add Moin as a foreign branch type.

  "not to mention WAY faster (wikis are always terribly slow for some
reason)"

time wget http://bazaar-vcs.org/
A wiki page (best of 3)
real    0m0.472s
user    0m0.000s
sys     0m0.008s

time wget http://doc.bazaar-vcs.org/bzr.1.0/
A static page (best of 3)
real    0m0.236s
user    0m0.004s
sys     0m0.008s

So static pages aren't even twice as fast.  If Andrew's finding
bazaar-vcs.org slow, perhaps something is wrong with his internet
connection.

"the main point was getting text based doc sources to drive the website
but be in the source code or very near it (thereby allowing patches,
review, etc but most of all a flow of information that allows anyone to
contribute but still allows a measure of consistency and refinement)"

"the difference is that you access the whatever-in-$VCS directly.  You
can edit text files properly and then submit changes as patches, instead
of working in random edits through some cumbersome web-app front end"

There are already ways of editing Moin in an editor.  Editmoin, for example.

"that has no quality control"

We already have pretty careful review of the Wiki, and most recent
criticism has been of the BazaarVsHg and BzrVsGit pages, which were
written mostly by Ian, and I helped with.  So they would certainly have
passed our current review process.

"but the quality problems with the Bazaar website far far exceed those
two pages. both in terms of content and performance."

I think fixing the content is best addressed by fixing the content, not
by changing the mechanism by which we update content.  Especially not by
making it harder to fix the content.

So in sum, I don't think Andrew makes a very convincing argument.

> Proposed site contents:
> 
>  * download (point to Launchpad download facility)
>    * source tarballs
>    * platform installers
>    * install instructions
>  * screenshots (of bzr-gtk, qbzr, olive)
>  * documents (include, or link to, generated html and PDF
>  * pointer to current code in codeview
>  * bzr plugins and related things:

I think plugin authors should be able to add or update plugin listings
whether or not they're on the Bazaar team, so I think this should stay
open for all to edit, i.e. wiki.

And if you want to automate the generation of some pages, well the Moin
API looks pretty hackable to me.

>   https://code.launchpad.net/~mbp/+junk/bzrsite-draft
> 
> My plan is to first get the current content converted into this new
> form more or less as it is, then put that up on a staging site for
> others to see.  Then I'll look at making it easier to do a news feed
> and announcements just by adding to a data file; then at better text
> and visuals.

Personally, I'd rather see this kind of effort expended on improving the
look of the documentation.  I don't see the process changes as an
improvement.

Aaron
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFHhuko0F+nu1YWqI0RAg3HAJ9NKTJfH75eoHRyEtSxCoK173IA/wCePfZ/
KjFz8nTaifm01GDx0ionnb0=
=+07+
-----END PGP SIGNATURE-----