11:19 a.m.
Greetings, all.
I've been working on a new project board for tracking our editorial work
and wanted to share it (along with a bit of context!). You'll find it here:
https://github.com/theopensourceway/guidebook/projects/1
## The workflow
The project board is a kanban-style board designed to help The Open
Source Way authors and editors visualize progress writing and editing
the book's contents.
When they appear, editorial issues ("something needs to be written,"
"something needs to be expanded," "something needs to be edited,"
"something needs to be corrected," etc.) will go on this board. They'll
move along the editorial workflow through the following steps, each of
which is represented with a different column on the board.
The workflow proposed here operates like this:
To Assign: Project managers have identified the issue as an editorial
issue and placed it on the board, but haven't yet assigned anyone to
work on it.
Assigned: Someone has agreed to write or edit material that addresses
the issue, and it's been assigned to them.
Drafting: That writer is now composing the material addressing the issue.
Draft Review: The writer has finished the draft and would like project
managers and editors to review it. Project managers and editors will
determine whether the writing sufficiently addresses the issue. If it
does, the card move "forward" to "Editing." Otherwise, it moves
backward
to "Drafting."
Editing: An editor is now reviewing and making editorial changes to the
material. If the editor determines that additional work is necessary,
that editor will move the card "backward" to the appropriate column
(i.e., back to "Drafting" if more writing is necessary, or to "Draft
Review" if authors and project managers should simply take another look
to confirm something). If the editor deems the work complete, then card
moves "forward" to "Formatting."
Formatting: A technical editor is reviewing the writing and "marking it
up" (in AsciiDoc) if it's not already. As part of this process, the
technical editor ensures that the work conforms to other technical
parameters (line spacing, footnote formatting, etc.) and will "compile"
as part of the book.
Final review: Project managers and any other stakeholders who may need
to review the work one more time have the opportunity to do so here.
Completed: Finalized issues are moved here; they're closed closed, and
their associated materials are merged.
## Sections, chapters, topics
The project board conceptualizes The Open Source Way as comprised of
"sections," "chapters, and "topics." Sections contain chapters.
Chapters
cover various topics.
As initially outlined,[1] the book consists of these sections:
- Introductory Material
- Attracting Users
- Guiding Participants
- Growing Contributors
- Measuring Success
- Avoiding Pitfalls
- References
Each of those sections has a corresponding "label" in the repository.
We'll assign chapters to sections. When we've determined the section in
which a particular chapter should be included, we can attach that
section's label to the issue associated with the chapter. For example,
the proposed chapter on "participant motivations" will likely appear in
the book section dedicated to guiding participants, so it gets the
"Guiding Participants" label in our repository.
Each section will contain several chapters. Chapters begin as issues
filed in the project repository.[2] At minimum, issues proposing new
chapters should elaborate:
- The subject, aim, and scope of the chapter
- Potential topics the chapter might cover
Modifications to or suggestions on chapters also appear as issues.
Project managers will triage these issues and, upon recognizing them as
editorial issues, assign them to the editorial project board (see above!).
Each chapter will cover several topics. Readers can file issues
suggesting new topics for chapters, revisions to existing topics, etc.
As topics expand, they may become their own chapters. As chapters
expand, they may become their own sections.
... and that's as far as I've gotten!
Feedback certainly welcome.
----
[1] https://github.com/theopensourceway/guidebook/blob/master/OUTLINE.adoc
[2] https://github.com/theopensourceway/guidebook/issues
2:49 p.m.
I really like this model that Bryan deployed into this project. (I'll get the email
out later from the meeting where we discussed this so you can have the audio/visual
discussion we had for reference.)
One social-workflow note I want to focus on within this structure are a few locations
where writers, editors, and reviewers can have some easy back-and-forth on ideas, changes,
direction, wording, etc. without moving the card back and forth between lanes.
Lanes in this board seem to represent who has responsibility for the content at that
moment--I've heard this described as, "Who has the pen?", in the concept of
a shared document but only one person can write/edit at a time.
What I'm envisioning is that e.g. during the Drafting phase, a writer may collaborate
with Shaun and other writers on language, approach, wording, etc. all while the card stays
in the Drafting lane--the pen is in the hand of the writer. Similarly, during the Editing
phase, Brian might be doing some back-and-forth with a writer to decide something. Or an
editor might do a whole batch of edits, and simply move the card back to Drafting or Draft
Review.
I guess I would say, maybe we should leave it up to individual writers, reviewers, and
editors at what granularity level they want to have back-and-forth while holding the card
in their board lane, and what granularity where they want to hand the card back for
someone else to hold the pen.
4:43 p.m.
"Who has the pen?" I love that.
I also except that back-and-forth to happen a lot, mostly in the various
threads associated with issues themselves. Whoever "has the pen," as it
were, will likely be the person responsible for acting on the outcome of
the discussion, whatever it may be. If the conversation is happening
while the article is in Drafting, then most likely the author is that
person. If the conversation is going on while the article is in
Formatting, then I suspect that person is a technical editor. Those
kinds of norms tend to emerge organically, though, so we'll just have to
wait and see how the community's editorial culture develops (the
*really* fun part!).
1902
days inactive
1904
days old
2 comments
2 participants
participants (2)
-
Bryan Behrenshausen -
Karsten Wade