Commit’s peer-to-peer bot helps community members tap into the vast expertise of our peers and colleagues to ask questions that span the spectrum from technical to personal. Here’s the latest question and answers.
Alex Gogan: How do you document how software is developed at your startup?
As our dev team grows beyond 10 engineers, we’ve noticed different expectations around code quality and process. To create a shared definition of what ‘coding and shipping products’ means, I’ve started to create documentation that outlines best practices and processes for everyone to follow. I’m involving individual contributors as well, to co-create the guidelines we want to hold ourselves up to.
How do you document and implement a shared definition and approach? Do repos (in analogy to open source) have a CONTRIBUTING.md file? Do you leverage pull request templates in GitHub or elsewhere? What do you cover in your guidelines?
Bill Monkman: I think I’ve done all of the above at various points, plus things like choosing languages, frameworks and tools that are self-documenting or encourage collaboration, schema-driven development, etc.
Depending on your organization and project setup, the CONTRIBUTING file may or may not make sense. If you have many repos and the same rules for all of them you may want to either have the guidelines in a separate place or choose a single repo to host them. If you have an onboarding guide for new engineers you may want to include some or all of this documentation wherever that lives.
If you have multiple microservices or repos for other reasons you may want to look at having an easy way to scaffold new projects, via GitHub’s template repo feature or other means, to create consistency.
Pull request templates can be very handy to help new contributors be consistent, especially if you are trying to standardize commit messages for auto changelog generation, though over time if the pull request templates are too big people may just zone out and ignore them. Best to keep them useful and concise.
I find the best way to encourage this stuff is to make sure everyone can get involved, and lead by example. Make sure your technical leaders are submitting PRs that give good examples, write good tests, etc., so everyone can see how it’s done in practice. Then you can use some of the better examples as resources to link to from your guides.
✅ ✅ ✅