linear, book-like output, incorporating
diagrams and text from each node.
Every Monday, we would meet to
review the work done during the preceding week. The team discussed and
resolved any overarching issues, and
clarified interactions between sections. Since each author could work
more-or-less independently (except
when they had to edit a node together
sitting side-by-side), issues could be resolved fairly easily. The most common
issues the team needed to resolve were
questions about style, tone, language,
and the framing of concepts.
Before each weekly meeting, we
would print the graph of all the work
done-to-date and post it on the wall
for the entire group to see. This poster
showed the week-by-week work done
by each team member and the links between sections and various subparts.
Not only was the graph useful for seeing where issues might arise, but it
was also a powerful motivator for other
team members to keep up.
During any single week, the authors
could work independently in parallel,
writing their nodes and creating any
substructures as needed. When they
discovered new prerequisites, they
were responsible for creating those explicit links between the nodes as necessary. Of course, other authors could
create new prerequisite links into their
territory as well. For the cross-links,
authors sometimes chose to work together side-by-side synchronously with
one acting as scribe to the discussion.
After eight weeks, the project was
completed—all the chapters had complete text, and all the cross-section prerequisite issues had been solved. The
printout resulted in a 220-page textbook.
Insights. The book was primarily written in parallel, solo-author sessions, with some short, key moments
of simultaneous work when issues
arose and resolutions needed to be
reached. The book was created over the
course of eight weeks, contrasting with
the Build-It which had preparation
work, one long day of dumping material, and a few days of cleanup. Atlas,
O’Reilly ( atlas.oreilly.com) and Book-Sprints ( www.booksprints.net) support
a process similar to this story.
This story is also similar to the one
told by Boellstorf et al., 2 where four au-
thors detail the creation of their coau-
day event where a small group of engi-
neers gather to simultaneously write
documentation about a specific piece
of technology. The Doc Build-It is a con-
strained activity, carefully designed to
enable engineers to impart their exper-
tise in a way that seems natural to them.
The Doc Build-It has three phases:
preparation, composition, and editing. During the preparation phase,
the writer meets with the technical lead to get a detailed overview of
the technology to be documented.
The writer then generates a prospective outline for the final document.
The outline is granular to the point
where each topic has two to three bullet points that suggest what content
should appear in the topic.
The composition phase is a single-day event. The writer asks the technical lead to invite three to five key engineers from the team to the event. At
the event, the writer first asks the engineers to give a verbal explanation of the
technology to get them into a teaching
mindset, a mindset that fits documentation. The writer then adjusts the prospective outline based on the explanation provided. Once the Build-It team
agrees on the outline, the writer invites
the engineers to claim responsibility
for the topics in which they feel they
have the most expertise. Their task is
only to capture the ideas in the words
that were spoken during the explanation phase. They then all write simultaneously in the same document. The
fact that they can see each other as they
produce the sections allows them to
align their styles (like level of detail),
make cross-references and double
check for accuracy.
The writer encourages the engineers to avoid concerns about diction,
spelling, punctuation, grammar, or
structure. Their contribution to the
document is their knowledge. This session normally takes about three hours
for relatively simple topics, and up to
seven hours for deeper topics.
After the composition phase, the
technical writer alone polishes the
document. Because the editing process can introduce semantic errors, the
writer circulates the edited document
for review with the engineering team.
The Build-It method had an enor-
mous impact on productivity. The cost
for one Build-It that I ran was an order
of magnitude smaller than a traditional
documentation approach costing an
estimated $1,900 instead of $18,000.
Other Build-Its produce similar re-
sults, and had ancillary benefits like
the identification of subtle bugs in the
technology. These discoveries are pos-
sible because the event captures the
attention of the most knowledgeable
people about a topic, who focus close-
ly on the design of the software in the
process of creating a document.
Insights. Doing work in clear phases
clarified the roles and simplified the
whole process. The technical writer
created an outline; the outline was
then edited after the explanation. Then
experts wrote down as much of their
knowledge as they could. This knowledge was then cleaned up by the technical writer and reviewed for accuracy.
A number of the following Stories have
similar mixes of asynchronous and
Story 2: Writing a textbook using
IDE, told by Dan. During the summer of 1988, I organized a team of 10
graduate students from the Stanford
School of Education to help write a
high school algebra textbook, fulfilling
a requirement to have experience in
designing coursework. The goal was to
create a complete textbook with a team
in less than 10 weeks. The team wrote
this text using IDE.
Of the 10 students, two acted as
lead designers and created an initial
outline, assigning each chapter to a
student author to create. To “write”
a chapter, the author had to create a
network of nodes in IDE, each linked
to other nodes signifying whether the
linked-to nodes were abstract concepts, conceptual details, refinements,
practice problems or dependencies.
During writing, the authors had to
identify any prerequisites that they
needed to assume while writing their
material. For example, the chapter on
Trigonometric functions relied on the
Pythagorean theorem to be introduced
in an earlier chapter, written by a different author. For that dependency, an
explicit prerequisite link would be created to signal that this concept (in one
chapter) depended on another concept
in another chapter (usually preceding).
The resulting network could then
be graph-walked (by following links of
a specified type) to produce a single,