[rfc] website improvements
Martin Pool
mbp at sourcefrog.net
Fri Jan 11 04:39:35 GMT 2008
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
More information about the bazaar
mailing list