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

[Karl Fogel]

Aaron Bentley <aaron at aaronbentley.com> writes:
> Karl Fogel wrote:
>> The mere fact that one would set up bzr differently as a casual
>> contributor vs a (potential) regular contributor is, itself, a huge
>> problem.
>
> I disagree.  I think a casual contributor just wants something that is
> simple and works, but a regular contributor is motivated to optimize
> their workflow.

Then perhaps we shouldn't present the regular contributor scenario at
all, at least not early on.  We can have pointers to it, tantalizing
footnotes that say things like "If you're planning to be a regular
contributor to project foo, then you can set things up in a more
efficient way -- see <HERE> for details."

However, although this is anecdotal evidence with a sample size of one:

I, a highly motivated contributor with some knowledge of VC systems and
prior experience with distributed version control, and expecting to be a
regular contributor, had a lot of trouble figuring out this optimized
workflow.  Indeed, even figuring out the right way to work on a bugfix
at all.

It's certainly possible that prior VC knowledge got in my way: caused me
to expect things to work a certain way, where if I'd been ignorant I
wouldn't have had those misleading expectations.

But the general response on this list to the diagnosis of "too complex
for noobs" has been agreement.  There has to be a reason for that :-).

>>   - It forces users to deal with unexpected complexity.
>
> I think casual contributors will only encounter complexity if it is
> pushed on them.  Regular contributors will seek it out.

I hope that's true.  The theory behind these scenarios is that if we can
structure people's initial experiences with bzr a bit more, then they
won't be confronted with complexity too soon.  Part of the reason to
write the scenarios is to figure out exactly what it *is* that people
are encountering.

>>   - It pushes users into making decisions about what kind of contributor
>>     they might become, before they have enough knowledge to make that
>>     decision.
>
> I don't think that follows at all.  A user can always start casual, and
> easily upgrade their set-up as they become more involved.  No one is
> forced to decide beforehand.

Great!  We'll need to document that upgrade step, then.

-K