If I had to choose one buzzword for Flock 2017 at Cape Cod, it would be ‘modularity’. Modules, module building, module testing, and module explaining seemed to be all over the place. I attended to give a workshop (with Aneta ŠP) about a proposed way to inject new life into the Fedora Documentation Project.
Not to be outdone, we had modules featuring quite importantly in our workshop, too. But not the kind of modules that make the rest of Fedora modular. Ours were much simpler conceptually. We presented them mostly as a means to an end for efficient authoring of documentation based on user stories.
Documentation Based on User Stories (My Participation)
The main idea behind our docs workshop stemmed from the following: while it’s great to have a lot of docs that users can refer to, it’s very hard to properly maintain them. How do we reduce the amount of docs, so that we only offer stuff that is really critical for users? At the same time, how do we eliminate some of the maintenance burden on docs contributors? From downstream work on Red Hat documentation, we have good experience with basing docs on user stories (yes, those agile user stories). This ensures good targeting as well as strong focus on the most important things.
Where does documentation modularity come into the picture? To achieve some basic consistency and to make docs work more accessible to one-off or first-time contributors, we have developed a set of templates. These greatly simplify the way writers can author user story-based documentation. To accompany that, we wrote a concise guide for potential contributors. It contains all the info they may need to start using the templates (see the GitHub repo). Our workshop aimed to introduce all these concepts and resources. We opted for a ‘learning by doing’ model. To that end, we invited all attendees to get their hands dirty with real-world docs. Together, we ‘modularized’ several user stories.
People liked the general ideas, and we even got a bunch of pull requests out of the workshop. So, I believe we’re on a good path. Fedora docs now also use new tooling (AsciiBinder replaced Publican) and a new source format (AsciiDoc replaced DocBook). Both publishing and contributing should be easier.
Look at the new website at https://docs.fedoraproject.org/. Join the docs team at https://fedoraproject.org/wiki/Docs_Project. And browse our repos at https://pagure.io/projects/fedora-docs/*. You can read more about the ideas and the workshop itself in the pre-Flock interview: Turning Legacy Docs into User-Story-Based Content. See also Aneta’s blog post: Two Docs Workshops at Flock 2017. Thanks to the Fedora Project for sponsoring us to attend – I think we turned the workshop into a success.
Thursday afternoon packed sessions that introduced Fedora modularity from basic concepts to practical examples of building and testing modules. It started with Langdon White’s, Ralph Bean’s, and Adam Šámalík’s short introductory talks. They were grouped into Modularity – the future, building, and packaging. Adam then continued with When to go fully modular?, Tomáš Tomeček with Let’s create a module, and Petr Hráček wrapped it up with Let’s create tests for modules/containers.
Learn More about Fedora Modularity
Even though the sessions were recorded, they were really hands-on. So, it might serve you better to take a look at some of the resources that people presented. First of all, go read the introduction to Fedora modularity at Building a modular Linux OS (with multiple versions of components on different lifecycles). The page provides all the info to get you started, including nice graphical schemes and links to the modularity mailing list and IRC channel.
If you want to start building modules, you will need to have a look at the module metadata definition template and the modulemd library used for manipulating it: https://pagure.io/modulemd.
Stef Walter’s presentation, Continuous Integration and Delivery of our Operating System, offered a very nice introduction into CI/CD. It included reasoning for its use, and the status of implementation in the Fedora (Atomic Host) building infrastructure. It wasn’t a very technical talk, which made it accessible even to people in the audience who had no previous experience with CI/CD.
Stef explained what integration tests can and cannot do, and in what ways they can free up human resources for working on more interesting things that robots cannot do (yet). The imaginative slides showed how a package travels through a CI pipeline and where along that path the system tests it and potentially quarantines it if broken.
The last time I attended Flock was in Prague in 2014. It was a much more massive event, with more people, more talks, and crucially, more talk. Really, the majority of the program consisted of presentations that talked about various aspects of the Fedora Project. While there were some workshops and offshoot hands-on sessions, it was totally different from Flock 2017.
The focus on ‘do sessions’ made this year’s Flock feel more like a hackaton than a conference, and I liked it. There was a sense of purpose in the air right from the start. One thing that, in my view, greatly helped to maintain this focus was the fact that the event and the hotel shared the same premises.
Before I arrived, I had considered that a nice touch that was going to save us some time and effort. But it proved to be a fantastic way of keeping all the attendees engaged all the time. My only nitpick would be that the actual conference rooms and space were depressingly cold, windowless, and a bit past their 90’s prime.