A presentation at FOSDEM in in Brussels, Belgium by Lorna Jane Mitchell
Beyond the README Crafting a better developer experience for open source projects Lorna Mitchell @lornajane@indieweb.social @lornajane.net (bsky)
Open Source Lifecycle From user to contributor. From contributor to maintainer. @lornajane@indieweb.social @lornajane.net (bsky)
DevEx for Users @lornajane@indieweb.social @lornajane.net (bsky)
Metadata Topic tags help project discovery. Introduce your project briefly. Key project measurements. @lornajane@indieweb.social @lornajane.net (bsky)
The art of README @lornajane@indieweb.social @lornajane.net (bsky)
README structure 1.Project purpose 2.Installation 3.Basic usage 4.Further resources @lornajane@indieweb.social @lornajane.net (bsky)
Documentation Documentation is a multiplier. •Use Docs-as-Code •Publishing is optional •Getting started •Platform-specific info •Advanced usage @lornajane@indieweb.social @lornajane.net (bsky)
The Tools we Build •Follow as many conventions as you can •Make the right thing the easy thing •Offer binaries or containerized tools if appropriate •Publish plugins/examples, or curate space for community work @lornajane@indieweb.social @lornajane.net (bsky)
DevEx for Contributors @lornajane@indieweb.social @lornajane.net (bsky)
Code of Conduct A code of conduct sets out expectations for all participants. GitHub prompts with a selection of CoC templates. @lornajane@indieweb.social @lornajane.net (bsky)
Contributing file @lornajane@indieweb.social @lornajane.net (bsky)
Contributing file Everything a new user needs to contribute. •Philosophy •Mechanics •Codebase •Quality •Finishing @lornajane@indieweb.social @lornajane.net (bsky)
Philosophy Are patches actually welcome? •A public resource with a private change process •A corporate project with a permissive license but no external contributors •A community-driven project @lornajane@indieweb.social @lornajane.net (bsky)
Mechanics •branching strategy •issue creation requirements •pull request creation requirements •naming conventions •quality checks and coding standards @lornajane@indieweb.social @lornajane.net (bsky)
Finishing What is the “definition of done” in the project? •docs •tests •changelog •something else…? @lornajane@indieweb.social @lornajane.net (bsky)
Local development Local tools shorten feedback cycle and improve developer experience. @lornajane@indieweb.social @lornajane.net (bsky)
Pull request reviews Transferrable skill from other code projects. •Be clear and constructive •Be prepared to add one more commit •Be consistent •Be responsive @lornajane@indieweb.social @lornajane.net (bsky)
CI really matters Give instant feedback on the things you care about (and can automate). •coding standards •prose linting •tests •changelog @lornajane@indieweb.social @lornajane.net (bsky)
DevEx for Maintainers @lornajane@indieweb.social @lornajane.net (bsky)
Review checklist Things to check on every pull request, documented. •helps contributors too •serves as onboarding for new maintainers •reduces your cognitive load •makes more consistent reviews @lornajane@indieweb.social @lornajane.net (bsky)
Maintaining fIle •like a contributing file •but for maintainers •write down the release process •the docs publishing process •anything else that the maintainer does @lornajane@indieweb.social @lornajane.net (bsky)
Automation Invest time to save time! Automate tests, syntax checks, build processes. Also spell checks, coding standards, file naming, pull request requirements. @lornajane@indieweb.social @lornajane.net (bsky)
Notification management Do you get too many notifications, too few, or the wrong ones? •route notifications •adjust watching •use codeowners •email rules @lornajane@indieweb.social @lornajane.net (bsky)
Outreach Your project is more than the code. Build and enable the ecosystem: •write about the project •feature cool projects using your project •check stackoverflow questions •speak at a meetup @lornajane@indieweb.social @lornajane.net (bsky)
Developer Experience in Open Source @lornajane@indieweb.social @lornajane.net (bsky)
Get in touch https://lornajane.net @lornajane@indieweb.social @lornajane.net (bsky)
Open source projects often start as “by developers, for developers,” but not all developers are the same. Users are the biggest group and they need clear, concise guidance to use the project effectively, while contributors require deeper insights into the codebase and processes. Maintainer experience matters too - making sure that the project is set up to work efficiently and make good use of their time and expertise. This talk explores how to go beyond the README to create a developer experience that caters to all three groups, ensuring your open source project is as welcoming, usable, and sustainable as it can be.
