[FM Discuss] Quick impressions following CiviCRM book sprint

[Edward Cherlin]

On Sun, May 10, 2009 at 4:27 PM, Andy Oram <andyo at oreilly.com> wrote:
> I agree with Adam and David that a complex narrative can't be achieved
> on a sprint, and is hard to do on a team even if there's a lot of
> time. The kind of in-and-out, case-study-marbled book conceived by the
> CiviCRM folks is like a Mahler symphony, and a sprint is a jazz combo.
> But someday we try doing fancy book structures over longer periods of
> time.

I can imagine doing this, but not in a single sprint. If we start from
user cases that have actually informed the development process, as for
example in Extreme Programming, then I think we will be able to do it
without getting bogged down. I am thinking that we can be as crisp,
friendly, and informative with cases as with standard content once we
understand what we are trying to do.

So my imagination has given me this scenario:

o Cases and software available before sprint.

o We explain how each case is supported somewhere early, in quick strokes.

o We put in sidebars (so as not to break the flow) on points where
features and cases illuminate each other.

o We think about revisiting the cases at the end.

They call this Tell them what you are going to tell them, then tell
them, then tell them what you told them. It needs a light touch, but
it can be effective where there is some initial confusion about what
the software is for and how it serves those needs. We certainly did
not need it for CLI, but we did a bit for Circumvention, and it might
be good for something as complex as CiviCRM.

> Regarding the outline: I think it's fine to call it brainstorming
> instead.

That's the standard term for it. I don't know of another.

> The outline worked particularly well on the Command-Line FSF
> sprint. I wrote it in about an hour (other people then suggested
> changes), and the final book came out looking a lot like it. But this
> was because the command-line is such a familiar subject. It has been
> covered before in a dozen books. Our treatment had some creative
> aspects (I take some credit for them), but it wasn't an exploration of
> totally virgin ground like the CiviCRM project.

You and others deserve more credit. I have used many Unix/Linux books
trying to learn various aspects of CLI, and have always gotten bogged
down by the essentially historical or encyclopedic approaches of the
authors. Nothing is in our book unless a beginner has a significant
use for it, and the way has been prepared with concise but effective
explanations of syntax, filesystem, standard i/o, and so on. It does
not pretend to be a sysadmin book in any way. Mission accomplished.

This is the book I wanted all along. I am actually using it, and
expect to come back to it several times more. Thanks to everybody.

> You have to hand it to the CiviCRM volunteers to conceive of such an
> audacious and subtle project.

+1

> We should look for some middle ground, though, between handing
> sprinters a canned outline and waiting for them to assemble before
> doing an outline (Index).

I'm hoping that we can try a few variations. Say, have someone (or
more than one person) draft an outline, and have some online
discussion of it before we assemble. Then take the time to get it
right at the beginning of the sprint. That doesn't mean finished in
every detail. It means a reasonable ordering of known topics and
issues, with indications of what content is available before we start,
to be rearranged as the narrative emerges, dependencies are dealt
with, or topics are merged or split.

> I'm worried that next time it will take much
> more than 3 hours. What if you have one or two sprinters who don't fit
> into the consensus, perhaps because they're inexperienced in the
> topic, inexperienced in reasonable expectations for a book, or just
> ornery?

Perhaps doing a little more beforehand will clarify things enough so
that the first morning will suffice. Perhaps the ornery will decide
that if it isn't going to be done their way, they won't come? Or
perhaps before it comes to that, they will produce their
counterproposals and we will have time to reconcile the versions?

> The idea of discussing particular paragraphs sounds great to me, even
> though it smacks of undergrad George Eliot classes. It depends on the
> leader knowing what he or she wants to convey and using the paragraphs
> effectively as lessons.

I thought the point was to resolve issues of style and organization,
rather than to teach.

> Andy
> _______________________________________________
> Discuss mailing list
> Discuss at lists.flossmanuals.net
> http://lists.flossmanuals.net/listinfo.cgi/discuss-flossmanuals.net
>



-- 
Silent Thunder (默雷/धर्ममेघशब्दगर्ज/دھرممیگھشبدگر ج) is my name
And Children are my nation.
The Cosmos is my dwelling place, The Truth my destination.
http://earthtreasury.org/worknet (Edward Mokurai Cherlin)