Add a page that describes how we work

[michielbdejong]

Whereas the various teams have their own documentation of how they work, there are some general guidelines that we want to follow across all teams. Here are some ideas! Comments welcome.

• we work remotely and coordinate via:

  • GitHub (code, PRs, issues, milestones / projects)
  • Slack
  • daily team standup meetings
  • weekly company retro meeting

• The teams are sovereign and responsible for setting and reaching their own goals in their own way

• We develop in the open, so we constantly push our work to a branch

• We work with Cloud Development Environments and reproducible dev environments, e.g. docker-compose or some well-documented scripts. This includes branches, so a co-worker should be able to open a branch on e.g. GitPod and see what you are seeing (possible after following some additional well-documented manual steps)

• Our work is organised in projects, and each project is split up into milestones. Milestones are generally about 1 or 2 months of work, and project generally have 4 or 5 milestones. The team plans its projects and tries to complete them roughly on time, and then moves on to more projects (follow-ups or new ones).

• For the moment we have enough inbound leads and funding opportunities to keep us busy and growing, so for now the teams only have to take the projects that come in, make sure they fully understand the reasoning behind each milestone, then plan the work and execute it.

• Each team has a system for resolving and documenting project decisions as well as design decisions.

• Each milestone is split up into work items. Each work item is documented in a GitHub issue, in such a way that your colleagues can understand exactly what its definition of done is (what is included and what is not).

• If we discover extra things that need doing, we create extra GitHub issues

• Like issues, PRs should have a clear title and description

• Code should be clean and adhere to the coding standards of the code base they are part of

• When we make UI changes, we include screenshots in the PR comments. These should be easily reproducible using the dev environment scripts of the repo/branch, and maybe a few manual actions.

• It's up to the individual teams how they coordinate who reviews which PR, and if you're the only person working on a project then it's sometimes OK to merge PRs without review, but in general each PR should be reviewed by 1 other person, and if accepted, it can be merged.

• You can expect your colleagues to be responsive and your colleagues can also expect that of you. If a person doesn't show up in a meeting, or they don't respond to a Slack message within (their) working hours, or they don't respond to a question or request on GitHub for longer than 24 hours, you have a responsibility to ping them, so everybody in the team knows who is working that day and who has a day off, has flaky internet, is not feeling well, is busy coding, etc.