Public Impressions

[Erik Bågfors]

I agree that the documentation is kind of a mess right now.  I
actually think that lot's of them should be rewritten.  Even if you
look at the documentation that just landed in bzr.dev, they are not
very good.  The reason is that they were written before knits, before
metadir, before shared repos, before aliases, before checkouts etc.
Some parts have been upgraded, some haven't.

I believe that a there should be a introduction document, explaing
different ways to use bzr, then a few tutorials depending on which one
you want to work with

For example, the way I see it there are two major ways to use bzr, one
being the normal DVCS way that bzr has always supported, and the other
way being the normal cvs/svn way, with a central shared repo, and
checkouts.

I think the second one hasn't been documentet very well, mostly
because most bzr developers are not that interested in it, but I think
lot's of users will see a very nice way to go from svn/cvs to bzr in
this.

I've been thinking about writing a tutorial for that.

Regards,
Erik

On 5/5/06, John Arbash Meinel <john at arbash-meinel.com> wrote:
> I've been reading some posts from here:
> http://blog.ianbicking.org/dvcs-mini-roundup.html
>
> And the biggest thing I get from it is that we need to clean up our
> presentation to outside people. We have a lot of terms and
> functionality, and such. But I think we really need to take some time, and:
>
> 1) Clean up the Wiki. James B did a lot of great work in that regard,
> but it sounds like our tutorials are not very straightforward.
> Especially now that we have checkouts and repositories, I think we need
> to present things well.
> I'm not the greatest documentation person, but I was thinking some sort
> of very basic tutorial, which would only follow best practices.
> Something that could either start with the very simple "bzr init; bzr
> add; bzr commit". Or it could go a little bit more with a "bzr init-repo
> $wd; bzr init foo; cd foo ..".
> I think the latter is a much better "best practice" since it makes all
> of your branching underneath $wd dirt-cheap. And now that we have knits,
> it doesn't require copying *everything* everywhere. (With a shared repo
> and weaves, all of your revisions of every project get copied, with
> knits, only involved revisions get pulled).
>
> But more than just the Tutorial, we need someone to follow all of the
> links, and get rid of any cruft that isn't accurate anymore.
>
> 2) Manually go through the tutorial and make mistakes while we are at
> it. Just to get the real impression about how the interface works, and
> how it complains when you do something wrong.
>
> 3) Consider changing the program name. A lot of people don't like to
> type "bzr". My co-worker aliased it to "bar", because then his pinky
> doesn't have to move as much. It would be great if we could find
> something that only used home-row keys. The other problem with bzr on
> Qwerty is that it reuses the same finger for b & r (on dvorak it uses 3
> fingers, but the letters are just as spread out).
>
> Other than 'bar', I can't come up with any good combinations from the
> letters "bazaar". I suppose baa is pretty easy to type :)
>
>
> I think 0.8 is going to be an excellent release, with lots of great
> features, and vastly improved performance. But we need to get it out
> there in such a way that people can see that, and actually use it.
>
> John
> =:->
>
>
>
>