Website Review (Was: thanks and suggestion)

[Ian Clatworthy]

Alaa,

Thanks for this initial review and apologies for taking so long to get
back to you. Some thoughts below ...

Alaa Salman wrote:
> Hey Guys,
> 
> In response to the email thread below. These are my initial observations.
> 
> -doc.bazaar-vcs.org/bzr.dev/tutorial.htm has a TODO section that needs
> to be
> written, and perhaps we can add some features that were added after this
> was
> written. I can only think of tagging but i am sure there are others.

That would be great. Can you take this on?

> -bazaar-vcs.org/Olive needs an overhaul to correct some information and
> remove some old info

OK. Please contact Szilveszter re what you think ought to be changed here.

> -bazaar-vcs.org/FirstUseTutorial   this also needs a review, but i also
> think we can remove this node alltogether since this same info exists in
> the
> tutorial in a better format

I think we should delete this node altogether. It doesn't add anything
IMO over the other tutorials.

> -bazaar-vcs.org/BazaarBook  this is old and quite incomplete with the
> reference part just copying bzr help

I think the existing content can all go. Perhaps the page could stay
though with:

* a suggestion that authors contact some listed open source friendly
  publishers (0'Reilly, Red Bean, PragmaticProgrammers, PHI, apress,
  New Riders, Addison-Wesley, others?) if they would like to write
  an awesome Bazaar book

* a link to our Documentation catalog (which should be nicer RSN).

Once the doco is bashed into shape, it ought to contain "everything" in
there somewhere. But a great book is something else: it present the
right set of information in a way that makes readers say things like:

  "Wow! I never thought on doing it that way."
  "I never realised it could do that."

It's part tutorial, lots of tips and tricks, lots of pragmatic stuff
(e.g. recommended plugins, how to migrate) and part reference. Different
books need to be written IMO because the signal to noise ratios need to
be different for different audiences.

> -bazaar-vcs.org/BzrPlugins  this page is too long i think and also needs a
> review if some plugins are dead or are no longer needed and so on

Yes, yes, yes. I think this could be a *really* interesting project for
someone: explore what it would take to do a cool plugins registry site
along the lines of http://addons.mozilla.org. Failing that, just
cleaning up the list would be a nice start.

> General:
> In general, i think that the layout can be modified somewhat. Perhaps like
> Martin said, a formal website that advertises bzr and a pointer to the wiki
> which would include information and whatnot. The information on the wiki
> needs to be reviewed so that we don't repeat the same info in several
> places.

Yes, we want to get rid of redundant information that needs to be
maintained in multiple places.

I also suggest using the tutorial.htm(first point) as the official
> "book" and reviewing that after each release to ensure accuracy. This way
> the users know exactly where to go when first learning. I also believe we
> also need to review the different workflows(which i worked on before) and
> better display them since they ease the transition if any.

I've proposed a documentation set and in particular a User Guide along
those lines yesterday.

> This is after an initial overview, so i am sure there is more so please
> everybody chip in. There are also some documents that i could only reach
> through the search engine(which needs some work i think) but i am not sure
> if this is just me not finding the links.

http://bazaar-vcs.org/OrphanedPages shows things not linked anywhere.

> Let me know who can do what and how we could go and then we can start
> working if people are ready to help.

It's not hard finding things to do! With a few of us though, I'm sure we
can make some big improvements quickly.

Ian C.