May I continue to hone this practice into an art. 🙏🏻 This is my meditation for the day!

DevConf.CZ 2020 is the 12th annual, free, Red Hat sponsored community conference for developers, admins, DevOps engineers, testers, documentation writers and other contributors to open source technologies. The conference includes topics on Linux, Middleware, Virtualization, Storage, Cloud and mobile. At DevConf.CZ, FLOSS communities sync, share, and hack on upstream projects together in the beautiful city of Brno, Czech Republic.

devconf.info/cz/

This is my third time attending DevConf CZ. I attended on behalf of RIT LibreCorps for professional development, before a week of work-related travel. DevConf CZ is also a great opportunity to meet friends and colleagues from across time zones. This year, I arrived hoping to better understand the future of Red Hat’s technology, see how others are approaching complex problems in emerging technology and open source, and of course, to have yummy candy.

Sessions: Play-by-play 🔗

Event reports take many forms. My form is an expanded version of my session notes along with key takeaways. Said another way, my event report is biased towards what is interesting to me. You can also skim the headings to find what interests you.

Diversity and inclusion meet-up 🔗

Would you like to meet other attendees who stand under the umbrella of “Diversity and Inclusion” or would you like a introduction into what Diversity and inclusion is and why it’s a good thing? this is the session for you! All are welcome!

Imo Flood-Murphy

This was a short, informal session ran by Imo to network and get a high-level introduction to diversity and inclusion in open source. Everyone in the room introduced themselves and gave a short explanation of who they were or what projects they represent. I appreciated the opportunity to meet others and better understand how Red Hat approaches diversity and inclusion.

A suggestion for next time is to allow more unstructured time for conversations. I think fun icebreakers get folks comfortable in a short amount of time to help make connections for the rest of the weekend.

Lessons learned from testing over 200,000 lines of Infrastructure Code 🔗

If we are talking that infrastructure is code, then we should reuse practices from development for infrastructure, i.e.

1. S.O.L.I.D. for Ansible.

2.Pair devops-ing as part of XP practices.

3. Infrastructure Testing Pyramid: static/unit/integration/e2e tests.

Lev Goncharov

Lev shared best practices on building sustainable, tested infrastructure. Infrastructure-as-Code (IaC) was important to how T-Systems scaled their infrastructure over time.

My key takeaways:

1. Smaller components:
   1. More sustainable
   2. Easier to maintain
   3. Easier to test
2. Ansible Roles encourage best use practices for Ansible
3. Spreading knowledge is essential (if nobody understands it, the code is broken)
4. Code review creates accountability
5. Use static analysis tools (Shellcheck, Pylint, Ansible Lint)
6. Write unit tests (shUnit2, Rspec, Pytest, Testinfra, Ansible Molecule)

Content as code, technical writers as developers 🔗

In the open-source project Kyma, documentation is an integral part of code delivery. We, the project’s Information Developers, believe that using the same tools and methodology as your good old code developers, we can create comprehensive and accurate documentation. During our talk, we’ll share the whys and hows of our approach, showing you that the “developer” in “Information Developer” isn’t there just because it sounds cool. We’ll prove that creating documentation goes beyond linguistic shenanigans and salvaging whatever information there is from a trainwreck that is the developer’s notes. Testing solutions, finding our way around Kubernetes, tweaking the website, engaging with the community are just a few examples of what keeps us busy every day.

Barbara Czyz, Tomasz Papiernik

“Information Developers” is a cool phrase I learned. Barbara and Tomasz explained the value of technical writing and asserted documentation should live close to project code.

My key takeaways:

1. Documenting processes like release notes enables others to join with less barriers
2. Docs-as-Code (DaC): Visibility of docs across development process is important
   1. Placing docs with code encourages feedback loops and avoids silos
3. Put links to docs in visible places (e.g. API messages, console messages)
4. Management aside: Emphasize/incentivize value of technical writing in your team
5. Remember bridges across skill areas is possible (technical writers can also be community-oriented people too)

Uncharted waters: Documenting emerging technology 🔗

We can’t help but feel the lure towards the hot new thing, especially when it comes to technology. Part of that lure is the breaking of ground, venturing into the unknown, and working on solutions to new problems. But a lot of the same things that make emerging technology fun and exciting to work on are exactly why it can be difficult to document. These challenges are quite different to those associated with mature products.

This talk is for anyone working on new products and emerging technology, or just interested in learning about fast-moving documentation. It is for the developer as much as it is for the writer, since it usually falls to them to write the early docs before a writer is added to the team.

Andrew Burden

This was the talk I didn’t know I needed to go to.

Lately I work with “emerging technology,” which means different things to different people. Regardless of what emerging tech means to you, Andrew focused on how to write documentation in a fast-paced environment with “pre-release” technology, where things change fast and suddenly. Normally this is an excuse to not write docs, but Andrew showed, yes! It is possible to write good docs, even when context changes fast and often.

Key considerations of fast-paced technical writers 🔗

An even balance of these considerations helps get into a user’s mindset:

1. Scope / scale of release
2. Release schedule
3. Developer meetings / face-time
4. Exposure with $TECHNOLOGY
5. Deployment experience with $TECHNOLOGY

Surviving the information wall 🔗

The “information wall” is the endless wall of information and things to know about a project. If information is endless, how do technical writers survive?

• Take notes: Be like a scientist
• Take notes about your notes
• Be organized with your notes

Obviously Andrew was getting at the value of note-taking. Practicing note-taking skills is critical to keep up with the pace of change.

“Multi-Version Syndrome” 🔗

Sometimes you are writing features for things that will not be released in the next release. There is a risk of losing information across multiple releases (e.g. publishing the wrong thing too soon, or the right thing too late). Clarify the release schedule as you go. A good safeguard against losing information is to rigorously understand release cycle cadence and priority.

If your product isn’t mature yet, anticipate change instead of avoiding it.

Access to technology is critical 🔗

Technical writers are often User 0. To understand the technology, you need access. There are interactive and non-interactive ways of getting access. Interactive ways are preferred because they are always reproducible.

• Interactive
  • Deploy your own
  • Get someone else to deploy it for you (but lose install context)
• Non-interactive
  • Live demos
  • Demo videos
  • Asciicinema (CLI-oriented)

Other takeaways 🔗

• Screenshots have high maintainability cost; avoid if possible
  • Sometimes good stop-gaps until something more maintainable
• Where to begin? Make a table-of-contents for the Minimum Viable Product
  • Never underestimate outlines (ahem, like how I wrote this blog post…)
• Avoid documentation scramble near release day:
  • Make lists / check-lists
  • Take more notes
  • Pre-release checklist
  • Think now, and for the future
• Audit your docs: On-boarding new people is a powerful opportunity to test out your docs

Thanks Andrew for a deep dive on this narrow but important topic.

Community management: not less than a curry 🔗

Every volunteer joins an Open Source community for a reason. The reasons could range from technical gains to finding his/her/their passion. This community of diverse volunteers require a leader who can not just mentor them with their interests but also a manager managing the community activities in terms of community engagement and planning. A community manager is not less than a candle of light and in this presentation, I would be highlighting my learnings and experiences about starting a community from scratch around a project and maintaining a healthy community management practices.

Prathamesh Chavan

Prathamesh designed an activity to help the audience understand community management. My key takeaway was community management is about connecting and understanding others as their authentic self.

In the activity, Prathamesh passed papers and pens to the audience. His session had three steps. Between each step, all attendees traded papers with another attendee:

1. Define a project idea (why, how, what)
2. Identify challenges to idea (i.e. questions)
3. Answer challenges

It reminded me of a similar workshop I attended before. This inspired me to work on my own workshop idea for a future conference.

Cognitive biases, blind spots, and inclusion 🔗

Open source thrives on diversity. The last couple of years has seen huge strides in that aspect with codes of conduct and initiatives like the Contributor Covenant. While these advancements are crucial, they are not enough. In order to truly be inclusive, it’s not enough for the community members to be welcoming and unbiased, the communities’ processes and procedures really support inclusiveness by not only making marginalized members welcome, but allowing them to fully participate.

Allon Mureinik

Allon recognizes the importance of diversity, but asking for improved diversity is one side of the coin. A friend recently shared a powerful quote with me: “If diversity is being invited to the party, inclusion is being invited to dance.” Allon’s message was to dig deeper on including marginalized people in our project communities.

He identified ways we accidentally make our communities less inclusive because of our cognitive/unconscious biases. Everyone has blind spots! Allon suggested ways to be more conscious about inclusion in open source:

• Knowledge barriers
  • Procedural knowledge, not just technical
    • How do you submit code? File a bug? Make meaningful contributions? These need to be documented
  • Documentation fosters inclusivity
• Language barriers
  • Working proficiency in English not universal
  • Conversations have extra barriers (e.g. communicating complex ideas, understanding advanced words)
• Time barriers
  • Work schedules no longer 9 to 5
  • Remember other folks in different time zones
  • On giving feedback: Fast is not a metric! Be smart
    • Merging PRs while others are away, or shortly after opening it
    • Allow time for input on non-trivial changes
• Transparency barriers
  • If not in the open, it didn’t open
  • Negative example: Contributor makes a PR, reviewer has face-to-face conversation with contributor, reviewer merges PR without public context
  • Default to open: in many ways
    • If you can’t be open, at least be transparent

Diversity in open source: show me the data! 🔗

How diverse is your work environment? Diverse communities are more effective, they allow us to share the strengths of the individuals who make up the community. Have you ever looked around and noticed that most of our Open Source communities are predominantly male? Why do you think that is? We’ll use gender diversity as a case study and share some intriguing data points. Let us convince you why it’s so important.

Regardless of your gender, we would love for you to join us! We will also give you some tips on how you can make a difference.

Serena Chechile Nichols, Denise Dumas

Serena and Denise divided the talk into two sections: metrics and action. The way they presented, they brought the audience on the same page by visiting a variety of metrics and then transitioned to an empowering discussion about changing trends we see.

Next time, I hope to see expanded messaging by defining diversity beyond only women. Diversity was frequently tied to gender participation metrics in open source. While women are underrepresented, there are additional aspects of identity that can compound discrimination. Race, socioeconomic status, nationality, sexual orientation, and more also play a part in understanding challenges collectively faced in inclusion work.

The data 🔗

• Gender differences by # of contributors:
  • GSoC 2018: 11.6% female-identifying contributors
  • OpenStack: 10.4% female-identifying contributors
  • Linux kernel: 9.9% female-identifying contributors
• U.S. Dept. of Labor: 22.2% of technical roles filled by women
  • 2014-2019: More women entering tech jobs at companies like Apple, Microsoft, Google, etc.
• Years of experience by gender (<9 years):
  • 66.2% female
  • 52.9% non-binary/queer
  • 50.1% male
• GitHub user and developer survey:
  • 95% male
  • 3% female
  • 1% non-binary

Let’s make things better 🔗

Serena and Denise asserted diversity creates change. All changes come with challenges. Diversity can increase the friction in the process, but that is okay. They emphasized the need for multiple perspectives see past our initial biases (conveniently covered by Allon in the previous talk).

This transitioned to questions, comments, and thoughts from the audience. One interesting point was using the phrase, “we don’t do that here” to create and set norms. I gave a suggestion to look at projects you already participate in and see if there is a diversity and inclusion effort there already. If there is, see if there are ways to help and get involved. If not, consider starting one (or network with the Open Source Diversity community).

To wrap up, one recurring theme of Serena and Denise’s talk is to make time to step back and evaluate the bigger picture. Questioning our biases is an important skill to practice. We need the space and time to recompute!

Candy Swap 🔗

Do you have a unique sweet dessert or candy from your country or hometown? Do you love to try new and exciting foods from around the world? Spend an hour with fellows as we share stories and candies from the world with each other. Participants are invited to bring a unique confectionary or candy from their country or city to share with multiple other people. Before going around to try yummy things, all participants explain what item they bring and any story about its origins or where it is normally used. After sharing, everyone who brought something rotates around to try candies brought by others. After all participants have had a chance to sample, the rest of the community is invited to come and try anything remaining.

Jona Azizaj, Justin Wheeler

I am biased when I say this is one of my favorite parts of conferences I go to. Jona originally proposed the candy swap for DevConf CZ. After unexpectedly adding DevConf CZ to my travel list for 2020, we teamed up to share the sweet tradition from Fedora Flock to DevConf CZ! This is one of my favorite conference traditions because I get to know other attendees in a context outside of technology. And food is always an easy way to win me over.

Instead of listening to me, see what other people have to say about it:

Time for the international candy swap! There are so many things to love about #DevConf_CZ but the geographic diversity of attendees might be my favorite part. Thank you for organizing, @jonatoni & @jflory7! pic.twitter.com/rU1ETp5aTa

— Mary Thengvall (she/her); mary-grace.bsky.social (@mary_grace) January 25, 2020

The "sweetest" activity of #devconf_cz: Today at 3 PM! 🍬🍫
Join Candy Swap, share candies, sweets and stories with others from around the world! https://t.co/OlfdmgGa3a pic.twitter.com/Jnlqi3lsaq

— DevConf.CZ (@devconf_cz) January 25, 2020

Candy Swap time at #DevConf_CZ 😍 pic.twitter.com/zFCNnXZoJf

— Jona Azizaj👩🏻‍💻 🥑 @jonatoni@mastodon.social (@jonatoni) January 25, 2020

Well I experienced this for the #Flock 2019. It's a great opportunity to know the tastebuds of diverse people and enjoy! :D

— Aal (Alisha)🌻 (@withloveaal) January 26, 2020

From Outreachy to cancer research 🔗

Outreachy program is helping women and other underrepresented people to make first steps in tech career. Picking a project, making first open source contributions, working on assigned project and learning from advanced people. But what happens when this three months are over? Can Outreachy be a lifechanging experience?

I will share my story of conversion from a chemist and full time parent into a Fedora Outreachy intern and how I found my place as a junior software developer in cancer genomics research at IRB Barcelona.

Lenka Segura

This was a favorite of the weekend. “Fedora Outreachy intern Lenka Segura on how Outreachy opened the door for her career to cancer research at IRB Barcelona!”

I put effort into live-tweeting a Twitter thread. Get the full scoop there!

Connect and grow your community through meetups 🔗

Open source communities collaborate in a multitude of ways - chatting on irc, submitting issues and contributing code on GitHub, discussing and sharing ideas on reddit and other social channels. Face to face gatherings add another dimension to that, where community members can learn and share their experiences. Local meetups provide a venue for people with similar interests to socialize and connect. However, organizing meetups is not trivial. How do we encourage and motivate the community to arrange meetups, and to keep the momentum? In my one year with the Ansible community, we have doubled the number of active meetups in Europe. These meetups are community driven, rather than Red Hat. Find out how we use metrics to analyze the situation and needs, and the steps we are taking to reach our goals of connecting with even more community members. Learn from our mistakes and challenges (100 RSVPs and only 20 turned up?), plus some tips to make your meetups more inclusive.

Carol Chen

Carol explained the role of local meet-ups around the world in building communities around software projects. She emphasized that single metrics are not always useful, so it is more helpful to evaluate on multiple areas. The most useful takeaway for me was the 5 W’s: why, who, what, when, where.

• Why? Common curiosity (noticing something new in your community)
• Who? Connections and networking
• What? Concise, compelling content
  • Consider venue travel (how to make it worth their while?)
  • Provide alternatives to git-based submissions
  • All talks don’t have to be technical! Diversify to appeal to wider audiences
    • Announcements for future events, work-life talks
    • We are more than just the technology we work with
• When? Consistency
  • Helps with venue scheduling
  • Helps retain attendee focus and build habits

Carol also gave suggestions for common points to think about for improved inclusion. All of these need active, not passive inclusion.

• Special needs / disabilities
• Food allergies
• Beverage preference (often alcohol/non-alcoholic)
• Language
• Traffic-light communication stickers
• Photography lanyards
• Gender pronouns

Beyond DevConf CZ 🔗

While the sessions are excellent and fulfilling (and sometimes frustrating when you miss a good talk with a full room), DevConf is also more than the sessions. It’s also the people and conversations that happen in the “hallway track.” It was nice to see many old friends and make new ones.

I spent a few extra days before and after DevConf CZ in Brno. In some of that time, my colleague Mike Nolan and I rehearsed in-person for our FOSDEM talk the following weekend (to come in a future blog post). I also enjoyed coffee and waffles with Marie, Sumantro, and Misc!

A few memories of a great week in Brno

Until next time! 🔗

I learn a lot and have a lot of fun at DevConf CZ. I’m happy to return for a third year. Hats-off to the organizers and volunteers who pulled it all off. Each year, DevConf gradually makes improvements. It’s nice to see inclusion prioritized across the board.

Thanks also goes out to RIT LibreCorps for sponsoring my trip. Extra thanks to Jona Azizaj!

I created this for the RIT Linux User’s Group (a.k.a. RITlug). RITlug welcomes student-led projects for members to work on together. RITlug executive board members want to better encourage students to share and join projects for collaboration with the community (in the spirit of FOSS). To do this, the executive board members will create and offer both a template website and template documentation tools to introduce students to project development process. Then, students are better able to sustain a more diverse community around their projects.

“Start writing ReStructuredText already!” 🔗

The philosophy with this small project is: “Start writing ReStructuredText already!” I use Sphinx with ReadTheDocs as a deployment option across different organizations. I want a common base to later customize for a specific project’s needs.

The whole point of this project is to save time kicking off a new project’s recently-established documentation effort.

Sphinx Travis CI testing configuration included 🔗

Complex documentation tool chains need simple validation of successful builds. This avoids long periods where documentation may not build and the public docs are out of date. It also better engages core contributors to monitor and take care of their documentation.

A Travis CI configuration is included. Fork this repository and enable the repo on travis-ci.org to start running builds.

Add a star on GitHub 🔗

Does this sound helpful? Check it out and add a star at justwheel/sphinx-docs-opinionated-quickstart. The project is licensed under the BSD 3-Clause License; feel free to fork it and form your own opinions too.

Photo by Jānis Skribāns on Unsplash.

Deliverable items 🔗

The last deliverable items from my project are two (2) git patches, one (1) git repository, and seven (7) blog posts (including this one).

• Git patches (ansible.git and infra-docs.git)
• Git repository
• Blog posts

Closing plans 🔗

At the end of the summer, I was using a private cloud instance in Fedora’s infrastructure for testing my playbooks and other resources. One of the challenges towards the end of my project was moving my changes from my local development instance into a more permanent part of Fedora’s infrastructure. For these reasons, I had some issues with running them in a context and workflow specific to Fedora’s infrastructure and set-up (since I am not a sponsored member of the Fedora system administration group).

My current two patches were submitted to my mentor, Patrick. Together, we worked through some small problems with running my playbook in the context of Fedora’s infrastructure. There may still be some small remaining hoops to jump through for running it in production, but any remaining changes to be made should be minor. The majority of the work and preparation for moving to production is complete. This is also something I plan to follow up on past the end of the GSoC 2016 program as a member of the Fedora Infrastructure Apprentice program.

My patches should be merged into the ansible.git and infra-docs.git repositories soon.

Reflection on GSoC 2016 🔗

As the program comes to a close, there’s a lot of valuable lessons I’ve learned and opportunities I’m thankful to have received. I want to share some of my own personal observations and thoughts in the hopes that future students or mentors might find it useful for later years.

Planning your timeline 🔗

In my case, I spent a large amount of time planning my timeline for the project before the summer. Once the summer began, my original timeline was too broad for having smaller milestones to work towards. My timeline on the student application was more broad and general, and while it covered the big points, it was difficult to work towards those at first. Creating smaller milestones and goals for the bigger tasks makes them easier to work through on a day-by-day basis and helps add a sense of accomplishment to the work you are doing. It also helps shape direction for your work in the short-term and not just the long-term.

For an incoming Google Summer of Code student for Fedora (or any project), I would recommend creating the general, “big picture” timeline for your project before the summer. Then, if you are accepted and beginning your proposal, spend a full day creating small milestones for the bigger items. Try to map out accomplishments every week and break down how you want to reach those milestones throughout the week. I started using TaskWarrior with an Inthe.AM Taskserver to help me manage weekly tasks going into my project. But it’s important to find a tool that works for you. You should reach out to your mentor about ideas for tools. If possible, your mentor should also have a way to view your agenda and weekly tasks. This will help make sure your goals are aligned to the right kind of work you are doing for an on-time completion.

I think this kind of short-term planning or task management is essential for hitting the big milestones and being timely with your progress.

Regular communication 🔗

Consistent and frequent communication is also essential for your success in Google Summer of Code. This can be different depending on the context of how you are contributing to the project. For a normal student, this might just be communicating about your proposal with your mentor regularly. If you’re already an active contributor and working in other areas of the project, this might be spending extra time on communicating your progress on the GSoC project (but more on that specifically in the next section).

Regardless of the type of contributor you are, one thing is common and universal – be noisy! Ultimately, project mentors and GSoC program administrators want to be sure that you are spending the time on your project and making progress towards accomplishing your goals. If you are not communicating, you will run the highest risk of failing. How to communicate can vary from project to project, but for Fedora, here’s my personal recommendations.

Blog posts 🔗

Even for someone like me who spends a lot of time writing already, this can be a difficult thing to do. But no matter how hard it is to do it, this is the cornerstone for communicating your progress and leaving a trail for future students to learn from you as well. Even if you’ve had a difficult week or haven’t had much progress, take the time to sit down and write a post. If you’re stuck, share your challenges and share what you’re stuck on. Focus on any success or breakthroughs you’ve made, but also reflect on issues or frustrations you have had.

Taking the time to reflect on triumphs and failures is important not only for Google Summer of Code, but even looking past that into the real world. Not everything will go your way and there will be times where you will be face challenges that you don’t know how to resolve. Don’t burn yourself out trying to solve those kinds of problems alone! Communicate about them, ask for help from your mentors and peers, and make it an open process.

IRC check-ins 🔗

Whether in a public channel, a meeting, or a private one-on-one chat with your mentor, make sure you are both active and present in IRC. Make sure you are talking and communicating with your mentor on a regular basis (at a minimum, weekly). Taking the time to talk with your mentor about your challenges or progress is helpful for them so they know what you’re up to or where you are in the project. It also provides a chance for them to offer advice and oversight into your direction and potentially steer you away from making a mistake or going into the wrong direction. It is demotivating when you’ve spent a lot of time on something and then later discovered it either wasn’t necessary or had a simpler solution than you realized.

Make sure you are communicating often with your mentor over IRC to make your progress transparent and to also offer the chance for you to avoid any pitfalls or traps that can be avoided.

Hang out in the development channels 🔗

As a Fedora Google Summer of Code student, there are a few channels that you should be present in on a regular basis (a daily presence is best).

• #fedora-admin
• #fedora-apps
• #fedora-summer-coding
• Any specific channel for your project, e.g. #fedora-hubs

A lot of development action happens in this channels, or people who can help you with problems are available here. This also provides you the opportunity to gain insight into what the communication in an active open source project looks like. You should at least be present and reading the activity in these channels during the summer. Participation is definitely encouraged as well.

Balancing project with open source contributions 🔗

I think my single, most difficult challenge with Google Summer of Code was balancing my proposal-specific contributions with the rest of contributions and work in the Fedora Project. I believe I was a minority of Google Summer of Code students who applied for the program as an active member of the project almost a full year before the program began. Additionally, my areas of contribution in Fedora before GSoC were mostly unrelated to my project proposal. My project proposal mostly aligned with my intended degree and education I am pursuing. A lot of the technology I would be working with was new to me and I had minimal knowledge about it before beginning the summer. As a result, this presented a unique set of challenges and problems I would face throughout my project.

The consequences of this were that I had to spend a lot more time researching and becoming familiar with the technology before advancing with creating the deliverable items. A great resource for me to learn about Ansible was Ansible for DevOps by Jeff Geerling. But I spent more time on learning and “trying out the tech” than I had anticipated.

This extra time spent on research and experimentation were in tandem to my ongoing contributions in other areas of the project like Community Operations, Marketing, Ambassadors, the Diversity Team, and as of recently, the Games SIG. Balancing my time between these different areas, including GSoC, was the biggest challenge to me over the summer (along with a separate, part-time job on weekends). A separation of time to different areas of Fedora became essential for making progress on my project. What worked well for me was setting short-term goals (by the hour or day) that I wanted to hit and carry out. Until those goals were reached, I wouldn’t focus on anything other than those tasks.

Special thanks 🔗

I’m both thankful and grateful to those who have offered their mentorship, time, and guidance for me to be a member of the GSoC Class of 2016. Special thanks go to Patrick Uiterwijk, my mentor for the program. I’ve learned a lot from Patrick through these past few months and enjoyed our conversations. Even though we were both running around the entire week, I’m glad I had the chance to meet him at Flock 2016 (and hope to see him soon at FOSDEM or DevConf)! Another thanks goes to one of my former supporting mentors and program administrator Remy DeCausemaker.

I’m looking forward to another year and beyond of Fedora contributions, and can’t wait to see what’s next!