screencasts.bazaar-vcs.org

[Ian Clatworthy]

Colin D Bennett wrote:
> On Fri, 20 Jun 2008 12:26:33 +1000
> "Martin Pool" <mbp at canonical.com> wrote:
>> On Fri, Jun 20, 2008 at 7:19 AM, James Westby
>> <jw+debian at jameswestby.net> wrote:
>>> I'd like to make it more of a site than just dumping the videos
>>> there, but it should perhaps be integrated with docs.bazaar-vcs.org,
>>> what do you think? Can anyone see a good way to integrate the
>>> screencasts in to the existing documentation that would supplement
>>> what is there?

My main concern with linking from the doc to screencasts is "stability".
When engineering IT systems, more stable subsystems shouldn't reference
less stable ones, e.g. it wouldn't make sense for bzrlib to reference
an API in a plugin. If the core, bundled doc begins referencing
screencasts, we need to be committing to stable URLs and QAed content.
It might be a bit early for that?

Don't get me wrong - I think screencasts are a *great* idea and I
want us to have lots of them! I'd prefer referencing them from Wiki
pages though, at least initially.

>> At the moment the doc site is a bit dry, since it contains rendered
>> forms of what was in the source tree for various releases.  The main
>> jumping-off point for it is bazaar-vcs.org/Documentation.  You could
>> certainly link the docs from there.  Generally the in-tree
>> documentation is the more official or somewhat more formal stuff.
> 
> Let me just say that I think the Bazaar User Guide is really great.
> I did not find it dry at all.  The clean, simple, beautiful format
> actually enticed me to learn reStructuredText and put it to use for
> lots of my own writing and documentation purposes (and borrow+improve
> upon the RST style sheet it uses). As for improvements to the user
> guide, I think more in-depth explanations of things would be nice, such
> as how "bzr send" works (what is "submit" branch, exactly? bzr send
> refers to it [6.4] and so does 10.1.

As James said, thanks for the positive feedback. I agree we need to
better explain send and the various locations: public, submit, etc.
Only last week, I used send incorrectly trying to submit incremental
patches - i.e. patches based on other patches - so there's clearly room
for better explaining some of the neat things send lets you do!

There has also been a huge amount of innovation in Bazaar since the
User Guide was written. I'd like to improve the Guide in coming
months to talk more about Looms, stacked branches, email based
workflows, GUI tools, working with large projects, searching and so on.
There's an immense amount of neat stuff in Bazaar and concise, clear
documentation helps more people be more productive sooner. At the end
of the day, that's what Bazaar is all about, to me at least.

If you ever feel like adding a section, feel free to propose one.
If you want to discuss ideas for sections before writing them,
you can email me (CCing the list) or catch me on IRC.

Ian C.