Beyond the README: Crafting a Better Developer Experience for Open Source Projects

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)