The Critical Role of Documentation in Open Source Success

Imagine diving into an open source project that seems perfectly designed to solve your problems, only to hit a wall due to a lack of clear documentation. This frustrating scenario is all too common in the open source community, where projects burst with potential yet falter in execution due to poor or absent documentation. The absence of well-structured guides, clear examples, and detailed installation instructions can turn an enthusiastic user into a disillusioned passerby.

In this session, led by Alanna Burke — community manager, developer advocate, and seasoned documentation writer — we will explore why documentation is not just an add-on but a fundamental component of any successful open source project. Alanna will share practical strategies for embedding documentation into the development lifecycle, ensuring that it receives the attention it deserves from the start.

We will discuss methods to engage the entire community in documentation efforts, from the core team to casual contributors, and demonstrate how well-maintained documentation can drive a project’s growth, facilitate user onboarding, and enhance community contributions. Join us to understand how transforming documentation practices can lead to more robust and resilient open source projects.

• May 2024
• Webinar
• Link to video

AI is here, and it's everywhere. How do we know what's real and what's not?

If you’ve been on the internet or watched the news this past year, you’ve heard about AI. Chat GPT, Midjourney, and thousands more tools seem to be taking over. And while they can certainly be useful, and the technology is exciting, it can be hard to determine what content has been generated by a computer and what was created by a human being.

In this talk, we’ll discuss some of the types of AI content generation and what they produce, and what to look for in order to differentiate between AI and human content, both written and visual. We’ll talk about why it’s important to be able to discern between the two, and the issues surrounding AI-generated content. Users will come away with a better understanding of AI-generated content and what it looks like, as well as how to spot it.

• March 2024
• Conference Talk
• Drupal Camp NJ
• Link to video

Protecting your work-life balance on a global 24/7 team

There are some great benefits to working with a global team - for instance, no one ever needs to work around the clock, because issues can be handed off as the next “shift” logs in for the day. However, it can be difficult to log off and put work out of your mind when you know someone is always working. How do you establish a mindset that lets you log off guilt-free when your working day is done?

In this talk, we’ll go over strategies for unplugging, dealing with guilt, and other issues that can crop up in these situations. Attendees will come away with actionable ideas for protecting their time and creating more work/life balance.

• June 2024
• Conference Talk
• DrupalCon Pittsburgh
• Link to video

Creating a Culture of Documentation

Picture this: you’ve found a new project on GitHub. It does exactly what you’re looking for, and it’s open-source. Amazing! So you roll up your sleeves and get to it. But then, you run into an error. You Google it. You find similar queries, but never the answer. You pour over the code. You search for anything documenting this project, but keep coming up empty. This project would be perfect, but no one ever documented it.

Far too often, the information we need is never found. It stays locked in the minds of the engineers who wrote the code. But what good is code that no one knows how to use? Documentation is every bit as important as making sure the project works. That buy-in can be hard. Stakeholders don’t want to pay for the time. Project managers don’t prioritize the work. Engineers don’t want to do it. The only way to solve this problem is to create a culture around documentation.

In this session, we’ll talk about how to elevate the status of the humble documentation to its rightful place alongside your code. We’ll cover how to integrate the documentation process into your existing processes so that your engineers are on board, and how to show stakeholders and others who push back that documentation is not only worthwhile, but essential to the success of your project.

• May 2023
• Conference Talk
• DrupalSouth
• Link to video

The struggle of getting an open-source community off the ground

Having an open-source project is great, but if no one is using it, there doesn’t seem to be much point in working on it, right? Lots of open-source projects are small and easy to integrate into your workflow, and so communities quickly form around them organically. But when you have a bigger project that requires some knowledge and buy-in, and a specific need, how do you get people enthusiastic and involved in your project?

In this talk, we’ll discuss how to start an open-source community from the ground up, and how to leverage your existing users and spaces. Attendees will come away with ideas and plans for how to take their project to the next level and get people excited and involved.

• Sept 2022
• Conference Talk
• DrupalCon Prague 2022
• Link to video

Kicking ass in your career while chronic illness is kicking your ass

When you think of chronic illness, what do you think of? Someone in a hospital with lots of tubes sticking out? Someone on disability who stays in bed all day and takes a lot of medications? Someone in a wheelchair who can’t get around easily? Those are some ways that people can experience chronic illness. However, the majority of people with chronic illness still have to live their lives. They go to work, they come home, they take care of their families, their pets, their loved ones. And then they wake up the next day and they do it all over again!

I have been managing several chronic illnesses for over a decade, and during that time my career has taken off in ways I never dreamed it would, but it hasn’t been easy. I work hard and take a lot of pride in my career. As much as sometimes I wish I didn’t have to work to provide for myself and my family, I don’t think I’d be happy without a fulfilling career. In fact, one of my biggest fears is that one day I won’t be able to work anymore due to my health.

In this talk, I’ll go over some of the high and low points I’ve experienced while advancing my career and managing my health, and how I deal when a flare up interferes with work. I’ll share some of my best advice for those in a similar situation. Attendees will come away with a better understanding of what it’s like to manage your life, your work, and your health, and how difficult it can be. My hope is that this talk will build understanding and empathy, and give some insight into what working life is like for those managing chronic illness.

• September 2022
• Conference Talk
• DDI Camp
• Link to video

Documentation as a deliverable - the business case for documentation

It’s no secret that documentation is often ignored, overlooked, or simply incomplete when it comes to many projects. Despite how essential it is, those working on the project often aren’t given the bandwidth to complete the documentation, as it isn’t regarded as being as critical as the code. In this talk, we’ll cover why this is wrong, and how to get all of your stakeholders on board to ensure documentation is delivered along with technical deliverables. We’ll go over strategies to get everyone on the same page, as well as how to find the bandwidth on your team to get the documentation done.

• April 2022
• Conference Talk
• DrupalCon Portland
• Link to video

Documenting an Agile Team - How to Keep up!

One of the biggest hurdles that documentation writers face in maintaining documentation is staying on top of everything as it changes. We need to know what’s going on in the organization to be aware of pending changes to the code, so we’re not blindsided by code changes that may break documentation links, and cause docs to be incorrect or outdated. Sometimes it can feel like we’re just trying to catch up with what everyone else has done, which can be exhausting and frustrating.

Ideally, engineers would update the documentation as they update code or add functionality, or work with you to update them as the coded feature is being worked on, but that doesn’t always happen. Additionally, the documentation team often has a better grasp of what is important to document for the end user, and is the team that bridges the knowledge gap between the engineers and the end users.

In this talk, we’ll go over strategies for keeping your documentation up to date when you have many engineers and fewer documentation writers.

We’ll cover:

• Keeping up with the pace of an agile team.
• How to be aware of changes before they happen.
• Being diplomatic when breaking changes are introduced.
• Technical solutions to help keep track of changes and problems in your docs.
• How to prioritize when you have to catch up to changes.
• Organizing your odds and ends.
• Writing excellent release notes.

• April 2021
• Conference Talk
• DrupalCon North America
• Link to video

Public speaking in the virtual era - conquer your fears

What really scares you about public speaking? What’s the worst thing that could happen? No, what’s the literal worst thing that could happen? Try to think of the thing that scares you most about speaking. I’ve presented with a searing migraine. I’ve been stuck in a Lyft waiting for a freight train to pass when my talk starts in 20 minutes (we made it, wish I’d been warned about that Nashville train). Virtual events have their own troubles - I’ve had the audio cut out in my virtual talk and the event team had to boot me out of the session because they couldn’t get my attention. Oh, and once I missed my own talk because I was dealing with a personal loss and mixed up the timezones - it’s pretty difficult to miss an in-person session at a conference.

And yet - here I am, happily employed, and still having my talks accepted. Because things happen! And frankly, I’m glad they have, because now I know that whatever life throws at me when it comes to speaking, I can handle it, whether I’m speaking in person or virtually. And so can you. With so many virtual events right now, the barrier to presenting is much lower - and I want to make sure you break down your personal barriers, as well.

In this talk, we’ll cover topics around presenting in general and the specifics of giving virtual talks.

• April 2021
• Conference Talk
• DrupalFest 2021