We started the second day of the FLOSS Manuals sprint with a circle encounter where each person shared some impressions of the first day. Several reported that they had worked on wikis and other online documentation before, but discovered that doing a book was quite different (I could have told them that, of course). They knew that a book had to be more organized, and offer more background than typical online documentation. More fundamentally, they felt more responsibility toward a wider range of readers, knowing that the book would be held up as an authority on the software they worked on and cared so much about.
We noted how gratifying it was to get questions answered instantly and be able to go through several rounds of editing in just a couple minutes. I admitted that I had been infected with the enthusiasm of the KDE developers I was working with, but had to maintain a bit of critical distance, an ability to say, “Hey, you’re telling me this piece of software is wonderful, but I find its use gnarly and convoluted.”
As I explained in Monday’s posting, all the writing had to fit pretty much into two days. Each of the four teams started yesterday by creating an outline, and I’m sure my team was not the only one to revise it constantly throughout the day.
Circle at beginning of the day
Today, the KDE team took a final look at the outline and discussed everything we’d like to add to it. We pretty much finalized it early int the day and just filled in the blanks for the next eleven hours. I continued to raise flags about what I felt were insufficiently detailed explanations, and got impatient enough to write a few passages of my own in the evening.
Celebrating our approach to the end of the KDE writing effort
The KDE book is fairly standard developer documentation, albeit a beginner’s guide with lots of practical advice about working in the KDE environment with the community. As a relatively conventional book, it was probably a little easier to write (but also probably less fun) than the more high-level approaches taken by some other teams that were trying to demonstrate to potential customers that their projects were worth adopting. Story-telling will be hard to detect in the KDE book.
And we finished! Now I’m afraid we’ll find tomorrow boring, because we won’t be allowed (and probably won’t need) to add substantial new material. Instead, we’ll be doing things like checking everything for consistency, removing references to missing passages, adding terms to the glossary, and other unrewarding slogs through a document that is far too familiar to us already. The only difference between the other team members and me is that I may be assigned to do this work on some other project.
(All my postings from this sprint are listed in a bit.ly bundle.)