[FM Discuss] Quick impressions following CiviCRM book sprint

[David Farning]

On Sat, May 9, 2009 at 4:49 PM, adam hyde <adam at flossmanuals.net> wrote:
> hey,
>
> it was an interesting sprint.
>
> i'm a bit sprint lagged right now, but i wanted to reply quickly so
> coffee in hand...
>
> the civicrm was another learning experience. i dont mean that in a glib
> way - i really learned a huge amount from this event. i think the
> questions andy poses are also questions i had considered as we went
> through the process.
>
> the role of an editor and the role of the outline are two big areas
> where we trawled through some new ground in this sprint, and this was
> due to the engagement and enthusiasm andy had for the project. without
> this i doubt we would have learned so much
>
> first up - the role of the outline. with the caveat that there are no
> hard set rules for a sprint, i have the clear impression that in most
> cases the Index must be created by the persons attending the sprint. we
> had a different experience with the Command Line manual because most
> writers (75% or more) were working remotely.
>
> however, what I saw with this sprint was that the expectations before
> the sprint that were evident in the outline far exceeded what was
> possible. this did not just allude to the scope of the material but also
> to the type of narrative desired. in this sprint the outline was largely
> created by people not in the sprint. and their expectation was to create
> a manual to end all manuals with a complex narrative - in the form of
> case studies that would wind their way in and out of the various
> chapters and be developed as a continuing story. This last aspect was
> particularly hard to get the team to let go of. it is my opinion, and
> please someone prove me wrong, that a complex narrative can be done in a
> sprint but it would severely reduce the quantity of material able to be
> produced.

What communities excel at is working on problems in parallel.  10
writers in a room, each focusing on the area that interests them most.
 What ties the group together is the mission (writing the book) and
release cycle (when their parts needs to be done).

Adding a narrative adds a large amount of complexity so it might be
something to reserve for more experience 'book sprinters.'

The community depends on modularity, itches, and interests.

> so, i would say that the outlining process was a good one, it has
> created scope for books that might follow, but it caused an unrealistic
> expectation about what could be done.

The outline it an interesting issue.  It can be a very useful tool for
coordination.  Taken too far, it can be stifling.  It is very common
for community projects to fail because of over planning.

A central figure dictating the expected outcomes and supported by
worker bees is very effective in a for pay situation.  It is less
effective when community members motivations are personal creativity
and expression.

This is not to say that an outline is a bad idea.  The question of how
complete the outline should be is a problem with which every community
struggles.

david


> the development and energy put by the civicrm team into the development
> of the outline caught me, and possibly andy, by surprise. the team
> really jumped into action via email about 1 week out from the event, and
> i think andy is right to say that once this energy has started to flow,
> its good to let it have its head. however, now looking back I think i
> would have been more vocal in sounding out that this is a brainstorming
> session, and that the Index - the thing that will actually determine
> what will be written is a different thing. and here perhaps we should
> consider changing the naming of this excercise from 'creating an
> outline' to 'brainstorming' or some such (I think 'brainstorming' isnt
> quite the right word, but im on my first coffee ;)
>
> so...in addition to this the Index is the template from which a sprint
> must work. and unless it is impossible, the Index should be created by
> the people at (in the real space of) the sprint.
>
> i found that when we met on the sunday night we topped the index off in
> about 3 hours and it looked different (much different) from the outline
> developed the weeks before. having the team create the Index is
> important for the following reasons :
> * everyone at the sprint understands the job at hand
> * it creates buy-in by all participants
> * it creates a good dialog from day 0
>
> The Index should be necessarily vague. It should just be a series of
> section headings and chapter headings. Anything with more detail will
> only confuse the team. The content should be worked out dynamically as
> the sprint goes. The sprinters should just be able to write on monday,
> 9am with a clear head. its far far easier to get them started and bring
> everyone inline as the week goes, rather than shackle everyone with
> constraints on what must be written where and when - this is my strong
> opinion, based on the experience of 8 or so sprints, but i do
> acknowledge that I havent tried the later approach. My feeling is that
> it might work in some instances - and the Command Line Intro might be
> one of those instances, although I am not sure how much the writing for
> this sprint was driven by contributors reading the outline and writing
> strictly to that, and how much was people writing and andy and I
> pointing the remote contributors at gaps we new were empty (based on the
> outline Andy created)
>
> So. Its not an exact science and experience is proving an interesting
> master.
>
> I have some thoughts on the role of a remote editor too, for now I will
> have a coffee and shower, ponder it, and write more later
>
> many thanks for all who helped make this sprint happen. Andy played a
> excellent role, not just in helping this sprint produce another
> excellent book, but by his active role in exploring the methodology and
> helping us all better understand the nature of the 'book sprint', and
> many thanks to Aco for getting the chat working so super - if you havent
> noticed, the chat now reports when people have started editing a chapter
> and this was super useful :)
>
> anyways...cooffeeeeeeeeeeeeeeeee
>
> adam
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
> On Fri, 2009-05-08 at 17:43 -0400, Andy Oram wrote:
>> I had a lot of fun working on this sprint, even though I was
>> disadvantaged by being off-site and even though I couldn't put in time
>> at all the moments when I would have been helpful (more on that in a
>> moment).
>>
>> I'm sure we'll all have insights after we evaluate the book that Adam
>> and crew are polishing off over the next few hours. But because I've
>> finished my part of the sprint (I'll certainly be back to review and
>> edit the draft later), I'll put out a few ideas while they're fresh.
>>
>> These ideas concern my role as ueber-reviewer and professional editor.
>> I can't judge many other things because I wasn't in the room with
>> everybody.
>>
>> I heartily endorse the sprint model. I've never seen a group of
>> authors be so productive as they routinely are during sprints. I want
>> to figure out how to maximize my effectiveness within this structure.
>>
>>
>> Outline and team spirit
>> -----------------------
>>
>> These areas are where I think this is where I've been most helpful so
>> far. This is because experienced sprinters hammered home to me that a
>> strong outline is crucial to a successful sprint. Ironically, though,
>> it wasn't ultimately I who designed the outline.
>>
>> The CiviCRM folks needed coordination. They have tremendous experience
>> and lots of ideas of what's missing from the documentation. Their
>> suggestions were deep: how to prepare your organization, how to map
>> your current practice onto CiviCRM, etc. But there was too much
>> centrifugal force during early discussions; nothing was coalescing.
>>
>> I'm pretty proud of how I handled the surfeit of creativity. I just
>> kept them talking, told them to write down ideas, and tried to
>> formalize what they wrote so it looked actionable.
>>
>> Eventually I realized we should have a vision statement. This might
>> sound like overkill for a sprint, but I think it's useful for every
>> endeavor. We didn't really work on it, but I threw out ideas I'd heard
>> and established a sense of a mission. I think this little digression
>> came at a good time, after I had heard a lot of individual visions and
>> could sense a direction. (That didn't help us later when we needed
>> it--see next section.)
>>
>> The reason I used the title "Outline and team spirit" together,
>> instead of breaking them up, is that the two endeavors went
>> hand-in-hand. The sense of "we're cookin'" and "we can do it" came
>> with work on the outline, and that spirit probably carried the sprint
>> forward.
>>
>> So about three days before the sprint--man, did we ever have outline.
>> In spades. I was not experienced enough to say, "Let's trim this," but
>> Adam recognized the need right away. We agree that it's good to
>> solicit lots of ideas. You can't turn on a spigot in the community and
>> then try to throttle it. But somebody had to choose the actual topics
>> to cover. That story comes next.
>>
>>
>> Stakeholders
>> ------------
>>
>> Having realized that the outline had to be trimmed. Adam ran into
>> trouble. His assessment, which sounds reasonable to me, is that the
>> people working on the outline--and particularly the group who had a
>> long conference call with me two weeks before the sprint--were
>> substantially different from those who came to the sprint. The overlap
>> consisted of just three people, I think. (Adam, feel free to correct
>> any of my impressions.)
>>
>> Worse still, I had been intensively involved in discussions around
>> scope and outline, but Adam had been more on the sidelines. Adam
>> selected some topics that made up a coherent scope, but it was
>> vehemently rejected by the sprint participants. I had signed off on
>> Adam's selection, but clearly there were too many different,
>> non-synaptic points of view. It's nobody's fault.
>>
>> Luckily, the sprint team quickly picked out an outline, so we got over
>> that mini-crisis.
>>
>>
>> Sprint-week editing
>> -------------------
>>
>> I don't know what happened among the team except that I saw people log
>> in early and stay late, but they were certainly productive. Like all
>> sprints, the level of professionalism in the actual writing varies,
>> but the ideas are almost 100% on target (and the things that were
>> inappropriate for the book got weeded out). I'll concentrate again on
>> my role.
>>
>> I jumped in quite early and edited a few chapters to try to set a tone
>> and a level of expectation. (Mostly: "does the audience need this?"
>> and "what's missing?") I think this was successful. When I came back
>> to those chapters, people had naturally added a lot more text--but I
>> think the focus and organization were also better. Of course, they
>> might have reached that point without me too.
>>
>> But then I fell behind. This was inevitable because I was still trying
>> to do most of my day job and lead a life. So for a couple days, gobs
>> of new text were added without my offering much review. Because I was
>> offsite and had just the extremely narrow channels of email and I for
>> communication, I also didn't know what parts people wanted help on
>> most of the time. (Occasionally I would come online at a good time and
>> someone could point me to a chapter.)
>>
>> I spent a lot of time editing, nevertheless. My log says 7 hours on
>> Wednesday (hard to believe), 4 on Thursday, and 3 today. I wonder
>> whether I could have focused my review to help set the direction
>> more. I don't know whether I should have reviewed different material,
>> or offered a different kind of review.
>>
>> My review did make a difference. But looking over the draft today, I
>> realized I could have done more. By this time it was too late to
>> recommend new sections or a big reorganization (although we can do
>> that later). Among the things I found too late to fix were:
>>
>> * A large section named "Constituents and Relationships," with five
>>   rich chapters, that jumps suddenly into a new level of detail with
>>   no intro. We need a little section saying "Here's where we got to,
>>   here's where we're going."
>>
>> * Two parts of different chapters that cover different but closely
>>   related topics about the architecture and software pieces needed for
>>   CiviCRM. I recommended they be blended, a subtle task.
>>
>> * A long chapter with two parts that I suspect are related in some way
>>   that's not clear. If they're closely related, they need to be tied
>>   together. Otherwise they should be two separate chapters.
>>
>> I suspect (and I think Adam will back my up) that at a sprint
>> pace--half a dozen people intensively writing--no single editor can
>> keep a book on track. The sprint participants kept it mostly on track
>> by talking with Adam and each other.
>>
>>
>> Edits and overlays
>> ------------------
>>
>> I'm an aggressive editor. When something doesn't flow right, I have no
>> scruples about breaking it into pieces, writing new parts, and making
>> a completely new chapter out of it. I do this even when I understand
>> the material imperfectly, knowing it will come out with errors.
>>
>> I need to edit this way because the perfect flow isn't clear to me at
>> the start. I have to work the clay, metaphorically speaking, to find
>> the solution. As each part comes out looking right, I can proceed to
>> the next or return to a part I edited before.
>>
>> On other projects I've worked on, this process works fine. The author
>> simply fixes the errors. My general structure is usually good, or is
>> easy to rearrange.
>>
>> One person on the sprint freaked out a bit at this approach. Adam told
>> me not to take him seriously, but I think his concerns were
>> reasonable. Time was tight and he didn't want to spend time on someone
>> else's mistakes.
>>
>> Now, I could have been a sophist and explained that I was not
>> introducing errors. Rather, the errors were implicitly in the text
>> already--because it was ambiguous, because it juxtaposed things that
>> were not meant to go together, because it somehow leaves an impression
>> the author doesn't mean to leave. But I didn't try to defend my
>> work. I made copies of test and inserted my ideas as comments without
>> changing the original (except for copy-editing). This worked fine.
>>
>> Andy
>> _______________________________________________
>> Discuss mailing list
>> Discuss at lists.flossmanuals.net
>> http://lists.flossmanuals.net/listinfo.cgi/discuss-flossmanuals.net
> --
> Adam Hyde
> Founder FLOSS Manuals
> German mobile : + 49 15 2230 54563
> Email : adam at flossmanuals.net
> irc: irc.freenode.net #flossmanuals
>
> "Free manuals for free software"
> http://www.flossmanuals.net/about
>
>
> _______________________________________________
> Discuss mailing list
> Discuss at lists.flossmanuals.net
> http://lists.flossmanuals.net/listinfo.cgi/discuss-flossmanuals.net
>