Short, task-based bzr doclets for real-world use cases.

[John Arbash Meinel]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Karl Fogel wrote:
> Ian Clatworthy <ian.clatworthy at internode.on.net> writes:
>> As you and others have indicated in this thread, I don't believe
>> our "fix a bug on a project" model is simple enough yet. I'd like
>> it to be something more like:
>>
>>   bzr clone lp:XXX
>>   cd XXX
>>   bzr branch trunk fix
>>   cd fix
>>   (hack, hack, hack)
>>   bzr send
> 
> Agreed... but I guess we're not there yet?  (At least, the recipe I seem
> to have settled on is more complicated than that... but see below).
> 
> So, I've created this page:
> 
>    http://bazaar-vcs.org/Scenarios
> 
> And written the first listed scenario:
> 
>    http://bazaar-vcs.org/Scenarios/Bugfix
> 
> Folks, if you can, please do one (or both) of these:
> 
>    - Flesh out one of the remaining scenarios
>    - If you think of another common scenario, add it to the list
> 
> Eventually, we'll need an editor -- a single person who looks at all the
> scenarios and makes sure they're giving consistent advice.  When they're
> not, we know we've found a place where bzr offers choices that the user
> doesn't know what to do with, and we'll have to pick a recommended way.

If I can give one recommendation to start with, can you use ReST for the
documentation, rather than Moin syntax? Our wiki supports both. I'll go
ahead and convert over the couple of ones that you've done so far. The
big reason is that it is consistent with our internal documentation, and
means we can just grab the wiki page and paste it into a file if we want
to move it to being bundled with the rest of bzr.


> 
> I can post a separate thread asking for an editor volunteer, when the
> time comes (hopefully soon!).  First, I'd like to see what people think
> of the list, and of the recipe I put in the first scenario, since it's
> probably a common one.

I hate to nominate someone else, but I'll have to say that so far Ian
has been doing a great job on refining our documentation, and would
probably fit a good role as "editor". It is certainly up to him if he
wants to take the job. I'm just giving him credit for what we have done
so far.

> 
> I cannot emphasize enough: fleshing out these scenarios is only the
> first step! :-) I think we'll probably want to reorganize the bzr home
> page and doc pages somewhat, to orient it all much more strongly toward
> new users and potential adopters.  When we do so, these scenarios will
> be an important part of reassuring potential adopters -- which means
> we'll have to position them in the right place.  
> 
> But let's get them written first.
> 
> -Karl
> 
> 

John
=:->
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (Cygwin)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iEYEARECAAYFAkl3N8cACgkQJdeBCYSNAANxIwCfcaOWv9F8IKbiDA986qnVkqvT
ZhgAoMINJlAH73JfACgru+2NKRmpHL08
=4krO
-----END PGP SIGNATURE-----