This year’s Flock saw two documentation workshops. One focused on reviving Fedora documentation as modular docs based on user stories. The other had participants helping to document Atomic Host features.

Reviving Fedora Documentation: Modular Docs Based on User Stories

At the workshop named Turning Legacy Docs into User-Story-Based Content, participants got hands-on experience with modular documentation. They also learned how this writing approach fits in with plans to revive Fedora docs.

Modular documentation is documentation based on modules, which the writer combines into assemblies (think articles). Each assembly documents a user story. See Modular Documentation Reference Guide for details.

After a short introductory talk, we rolled up our sleeves and started writing. Five people showed up for the workshop, and we had four pull requests at the end. We would have been able to submit more, but the workshop naturally transitioned into a conversation about modular docs tooling, writing workflows, and the word bolus. The last one isn’t really relevant to mod docs, so let me summarize just the first two.

A few important benefits of writing modular docs based on user stories:

• Easier onboarding thanks to templates.
• Experienced writers can help junior team members by pre-preparing the structure of assemblies and modules. These junior people, who might otherwise feel intimidated to start editing a large guide, just fill in small files (documentation modules).
• Convenient writing workflow involving different people at different stages. One person files an issue on pagure proposing a user story to document, another fleshes out the details (what modules the assembly should consist of), and others then choose modules they feel comfortable with.

Of course, modular writing has its challenges as well. For example, managing the docs can be more difficult because you need to navigate a repo with a large set of modules. But because long non-modular guides are also very difficult to manage, the transition to modular docs doesn’t seem to make things worse.

To learn more about modular docs based on user stories, see Documentation Based on User Stories on opensource.com and the repo for the Modular Documentation Reference Guide. Among other things, the guide provides guidelines on writing assemblies and modules. Contributions are welcome!

Atomic Host Docs Challenge: Who Can Write the Most Docs?

The Atomic Host has a number of interesting features, but many of them aren’t documented. The organizers of the workshop named Fedora Atomic Doc Work showed the participants a work-in-progress guide and asked them to fill in the sections that were empty.

After a brief introduction to explain the publication tool chain and the basics of AsciiDoc, we set to work. The task was to:

1. Fork and clone the repo for Atomic Docs.
2. Pick an issue, and comment on it to let others know someone has claimed it.
3. Write the docs!

A lot of the issues included existing resources (docs on GitHub, Red Hat docs, etc.) that we could use as a starting point to create the new Atomic docs. For example, see this issue for adding a section about how Atomic Host revolutionizes OSes.

To encourage everyone to try their best, Atomic-themed swag awaited the most significant contributors. Prizes went to people who submitted the most pull requests, worked on issues without any pre-prepared external resources, and to the most productive external (non-Red Hat) contributor.

A number of issues for the Atomic Host docs are still open and up for grabs. If you’d like to help, feel free to claim one for yourself. You might want to start with the Atomic Host Documentation Contribution Guide, especially if you are new to AsciiDoc and AsciiBinder.