The Documentation Fedora Activity Day held this past weekend in Raleigh, NC had an impressive collection of stakeholders across the Fedora, Red Hat and CentOS projects. It was certainly not your typical “hackathon” or “DocSprint.” There was much productive discussion, tools vetting, future planning, AND development.
Etherpad Export: Full Agenda and Notes
IRC Meeting Log: Friday
IRC Meeting Log: Saturday
IRC Meeting Log: Sunday
Docs FAD Fedora Badge

 

Participants

Pete Travis — immantetize (Austin TX, Fedora Docs Team lead)
Zach Oglesby — zoglesby (Baltimore MD, Fedora Docs Team member, former Lead)
Shaun McCance — shaunm (Cincinnati, Red Hat community docs)
Stephen Gilson — sgilson (Westford, Red Hat product docs)
Paul Frields — stickster (Fredericksburg VA, Red Hat Fedora Engineering)
Ryan Lerch — ryanlerch (Brisbane QLD Australia, Red Hat Fedora eng)
Silas Hensley — dsilas (Brno, Red Hat product docs)
Remy DeCausemaker — decause (Raleigh, Red Hat OSAS/Fedora community lead)
Jim Perrin — jperrin (Houston TX, CentOS Project)
Karsten Wade — quaid (Santa Cruz, CA; former Fedora Docs Lead)
Kushal Das — kdas (remote)
Nick Bebout — nb (remote)
Tummala Dhanvi — c0mrad3 (remote)
Corey Sheldon — linuxmodder (remote)

Day 1

Personas and User Stories

One of the key reasons for having the brilliant and talented Ryan Lerch here in attendance with us during the FAD, was to tap into his experience and knowledge about User Experience and User-centric approach to defining our problem space. Having so many stakeholders from a variety of Upstream and Downstream projects and teams was that we could accurately approximate most of the types of users that would be impacted by our toolchains and content strategy. After much discussion, these were the ten that we settled on:

1. Content Strategist
2. New Docs Contributor
3. Experienced Docs Writer
4. RH Content Professional
5. Drive-by Fixer
6. Reader
7. Publisher
8. Tools Maintainer
9. Subject Matter Expert
10. Doc Program Manager
11. Translator

These personas were then used to write a variety of “user stories” that follow a format of:

“As a _________________,
I want to _____________,
so I can ______________.”

This madlib-ian exercise was one of the more productive parts of the day, where we generated dozens of stories for each of these personas on post-it notes, which were then grouped and categorized on the whiteboard.

For future reading and reference (and hilarity) on User Stories, we were pointed to GoatUserStories (which in turn, inspired another UserStoryParodyAccount.)

Turning Stories into requirements

Once we had grouped and gathered the stories, we broke those down by area of concern into either “workflow” or “content strategy” (or broad based project-wide scope) so that we could tackle each concern with strategy. Post-its were then posted in “lanes” next to each user story from left-to-right, with concerns of the highest priority (and/or feasibility) to lowest. By the end of the day, we had clear consensus on our users, and requirements of each type of user for whatever toolchain or solution we went after. This was a KEY aspect of the FAD, because too often when you get groups of engineers together, it turns into a ‘tools-fest,’ and we get the cart going before the horse, and start at the wrong end of the process. The agreement of the problem space at the outset, with key stakeholders up and downstream in the same room, was an achievement in it’s own right, and actually was much easier to reach that we expected.

Report Out Video: Day 1

Day 2

Show and Tell

Once we knew who our users were, and what their requirements were, we were able to start researching potential solutions, and particularly, ones that folks in our group were already familiar with. These included:

pantheon
anerist
jenkins
buildbot
taskotron
jenkinscat
Docs2Drupal
pintail
mallard
ducktype
yelp-xsl
publican
Wordpress
Drupal
Zanata
asciidoctor
Pagure

After the tools demo, we agreed on a few proposed toolchains, and some CMS and Wiki solutions, and compared them to the top 20 priorities/requirements from each of our users. The results of this requirements vetting could be found here:

Requirements Vetting Grid: https://ethercalc.org/txnb0f8lewsz

After an intensive round of voting/rating, the winning result that came out was:

Pagure repos of asciidoc data Layer
Orchestration CI/CD/Translation Layer
pintail presentation Layer
Publication Layer

This helps us in a number of ways:

1. It moves us away from our very fragile existing publican flow.
2. Pagure allows for ‘drive-by’ editing in the browser, without requiring command-line or git, while still enabling that workflow and infrastructure for experienced FOSS contributors too.
3. asciidoc is a common, modern, and increasingly popular format used by a number of other projects, including CentOS and Red Hat Content Services.
4. With a proper orchestration layer, new commits can be tested and deployed to staging or other ‘one-off’ instances, to give immediate feedback on contributions (identified as a big barrier to sustained contributions))
5. pintail allows for a good “medium term” solution that lets us continue to publish our existing docbook based content, while preparing for new formats and information architectures of a more “knowledge base” type system.
6. The publication layer is mostly an afterthought, and can be implemented by a number of tools (e.g. git, rsync, ansible, or any other tool that allows for file transfer and manipulation.)

Report Out Video: Day 2

Day 3

Day 3 was much about breaking down our proposed toolchain into tasks to be taken on in the near future, and then turned into issues on our Pagure repo. This was also accompanied by a variety of hackery on the tools themselves, sending pull-requests upstream to dependent libraries, and connecting our stakeholders to continue effort moving forward.

Conclusions and Shoutouts

Big Shout-out to Paul Frields who developed the agenda, convened the diverse group of stakeholders, and kept us motivated and on task. Going forward, the Documentation Team is hopeful to acquire new contributors from other projects like RHEL and CentOS, but also different teams within Fedora, random “drive-by” patchers and contributors from the internet at large, and from our newly selected Google Summer of Code student. I think we’ve got a great short-term plan to improve delivery of our existing Docs, while preparing to overhaul our Content Strategy on the whole in the future, and port the wealth of knowledge already in our documentation into formats that can be useful to many users beyond our project.