[rfc] website improvements

[Martin Pool]

Thanks for replying (and Andrew too.)

> 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.

I'll ask Matthew to fix those particular things.  I feel that
frustration too, and

> >  * 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?

I actually meant, a Bazaar branch.  But yes, a Python script driving
it.  In part like your pretty_docs using Kid, but more integrated with
other things.

> > 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.

I don't know if you've ever done the wiki update tasks from the
ReleaseChecklist, but I certainly wouldn't describe it as easy or
instant.  It is really stretching it beyond what works well.

> 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.

No, www.ubuntu.com is no longer a wiki, from similar motivation of
wanting to avoid extensive hacking to control the look;
wiki.ubuntu.com is a wiki obviously, and is where the content that
needs to be most easily user-editable lives.  The majority of pages,
and probably the majority of the edits are in the wiki, but

>
> 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.

I think there would be more of a difference loading them from a real
browser, which will need to get CSS, images, etc.  From here (.au,
wireless) measuring using FasterFox, I have 1.788s for the doc page,
and 6.636s for the Bazaar home page.  So that's both ~4x slower, and
getting to a pretty long time in absolute terms.  It is probably more
to do with the theme than the hosting software though.

I think Andrew may have been talking about speed of editing rather
than loading.  Without measuring, I think it takes me on the order of
10x more time to save a page to a wiki, and open a new one for
editing, compared to doing the same between files in vim.  Even with
EditMoin it's slower.

> "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.

I'm not sure where this double-quoted text came from, maybe a long-ago
post of AfC?

I wouldn't say that the wiki has no quality control, clearly we do
review things there, or that having a site in a branch is a panacea
for quality.  I do think both visually and textually wikis make it
hard to have really polished content, which is what you want for a few
core pages.

The documentation has improved a lot after moving it from the wiki to
the tree.  Of course that is mostly because of Ian's hard work, and it
might have happened otherwise, but I think this contributed.

>
> 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.

ok

> 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.

What do you mean by 'look'?  I am working on having the docs
integrated with the rest of the site (eg having a navigation bar in
their html versions) using the docutils api.

-- 
Martin