sloecode-dev team mailing list archive

[Thomi Richards <thomir@xxxxxxxxx>]

Hi,

On 23 February 2011 22:35, Christopher <veebers@xxxxxxxxx> wrote:
> WRT the documentation (points 4 & 5), how many clients are we looking at
> providing help documentation for?

Well, We have several project groups using the system at the moment. I
think the thing to remember with the documentation is that there are
10 types of programmers: those that know how to use bazaar (and don't
need the documentation), and those that don't, and need simple
documentation.
>
> My initial thoughts on the help/docs would be that we have a main page that
> documents the main points then have links that branch out to the specifics
> (mainly regarding clients).
>

Agreed.

> For example it could read something like:
> * Blurb about Sloecode

I think this should just go on the front page.

> * Blurb about bzr
> * Description/Introduction to bzr (well, VCS) way of life
> * Outline of _our_ intended work-flow for those new to DVCS
>  (i.e.) You will take these steps: clone/pull, work, merge/commit, push etc.
>  make it step-by-step easy for them to use, stick to the basics.
> * Description of the plugin
> * Links to specifics for the users chosen clients to achieve the above
>
> Where each specific link will follow a template as well
> i.e. 1. Intro 2. download/install 3. how to achieve your work-flow steps.
>
> I dare say we could pilfer ideas from existing documents; for instance:
> http://doc.bazaar.canonical.com/latest/en/mini-tutorial/index.html
>

Yes, although I think we need our documentation to be more targeted.
Understandably, the official bzr documentation tries to cover all
options and eventualities. I think we can get away with hiding most of
the detail, especially since people who already know bzr won't be
reading it.

> I'm willing to help out with the doc writing.
>

Awesome!

> I have some experience (although I'm by no means an artist :) ) with webpage
> stuff, so I can spend some time looking into it's appearance unless you have
> someone else in mind? Could always collaborate etc.
>

I don't have anyone in mind - I suggest we work out what we want for
the web design before we actually do any redesign. We could either
meet up and discuss this, or we could start a LP blueprint and
collaborate on there. Your call, I'll leave it all to you ;)


> Totally agree with showing the repo details, should brainstorm what would be
> good to have and prioritise that as well.
>

I have an experimental branch that adds a branch log for all
repositories. I think it's at lp:~thomir/sloecode/revision-info
(that's from memory - look at LP if it's wrong). Right now it shows
the last 10 revisions for every branch. I'm working on it to produce
HTML (at the moment it's text output wrapped inside <pre> tags...
yuck!). Once it's done I'll merge it into trunk. I'm introducing
adapter/facade classes around the bzrlib Repository & Branch classes
so we can get useful information out of bzrlib without having to pass
these objects into template code.


Anyway, thanks for your input. I'm excited that we have something that
works and is useful...


Cheers,