Initial thoughts on Bzr docs

[John Arbash Meinel]

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

Matthew Revell wrote:
> Hey all,
> 
> Overall, I'm highly impressed with the Bazaar documentation.
> Stylistically, it generally crisp and straightforward.
> 
> 
> Missing docs
> -------------
> 
> My main priority is to ensure that there are no major gaps in Bazaar's
> docs. You'll have seen my meeting announcement already, where I'd like
> to discuss what's missing in the docs.
> 
> However, I don't see any reason not to kick off the discussion here
> before the meetings! You guys know Bazaar much better than I do :)
> 
> 
> Mini-tutorial
> --------------
> 
> Initial suggestions:
> 
>  * Rename to "Bazaar in 10 minutes" to emphasise ease of Bazaar, to
> show it requires little commitment from the user and to differentiate
> from the main tutorial.
> 
>  * Flesh out the text a little.
> 
>  * Use graphics: I'm really keen for your input here. I wonder if we
> need to find a way to break up the text but obviously there's no GUI
> to give us a flashy screen shots. Perhaps some illustrations? I may be
> totally off the mark here.

I think having some simple graphics to lay out "where is the Branch, where is
the Repository, where is the Working Tree, what data goes where when I do 'bzr
commit', etc" would be excellent.

> 
> I think we should put this mini-tutorial right up-front, not only in
> the documentation but also right up at the top of the bazaar-vcs.org
> home page. I think it's slightly lost where it is now on the
> bazaar-vcs.org home page.
> 
> I reckon it can be an excellent crossover between documentation and
> promotional material.
> 
> 
> User guide
> -----------
> 
> Along with the user reference, this is obviously one of the main
> places where we need to ensure we fill gaps.
> 
> Tutorial: I'd like to highlight this on the doc home page. I'd also
> like to break it down into smaller chunks, each chunk with an end
> goal. This would be similar in style to the Launchpad feature guide
> at:
> 
> https://help.launchpad.net/FeatureHighlights
> 
> Again, I'm largely reliant on you guys to help me find gaps in the tutorial.
> 
> Best practice and advanced topics: I wonder if these should be merged
> and renamed something like "Masterclasses". The smart server article,
> for example, could sit in either section. I'm very keen to add to this
> section and again look to you for suggestions. I think this is a great
> opportunity to introduce some of the community tools, as well.
> 
> 
> Thanks, I look forward to hearing from you :)
> 
> Next, I'll post some suggested rewrites of existing material to the list.
> 

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

iD8DBQFG++WgJdeBCYSNAAMRAukMAJoCT0Dtu3b22701wnrVyZoE2Ndv7gCfbF5b
bAUC4uRyKHmBSGXHyLJEKeA=
=yw/n
-----END PGP SIGNATURE-----