Document core contributor handbook

[garethbowen]

We have a range of docs for core developers for how to do certain things but they're spread out. Instead we want to put all core contributor resources in one place so that it's easy for contributors to find and other user types (app devs) don't end up in the wrong place by accident.

Resources that should be co-located:

• https://docs.communityhealthtoolkit.org/core/guides/releasing/
• https://docs.communityhealthtoolkit.org/core/guides/update-dependencies/
• https://docs.communityhealthtoolkit.org/core/guides/fixing-e2e-tests/
• https://docs.communityhealthtoolkit.org/core/guides/android/ (except for building flavours)
• https://docs.communityhealthtoolkit.org/core/guides/using-npm/
• https://docs.communityhealthtoolkit.org/core/guides/using-windows/
• https://docs.communityhealthtoolkit.org/core/guides/docker-setup/
• https://docs.communityhealthtoolkit.org/contribute/ (the whole section)

Move these to a top level section called "Contributor Handbook".

Missing documentation includes:

• Code design (a macro view of code style)
• Product quality (requirements like change management, CI, testing, etc)
• How to review code
• and probably much more...

[garethbowen]

@craig-landry Can you please review these suggestions to make sure we're on the same page before I start moving everything around?

[andrablaj]

@garethbowen thanks for sharing this ticket with me! I had a similar discussion with @craig-landry a few weeks ago around creating an engineering handbook for the Medic team (+ public, depending on the content).

You can find below a draft for how that could look like.

What?

The Product @ Medic Handbook contains a compilation of resources, best practices, and guidelines that guide how we try to operate as a team.

Why?

• At the moment, Product documentation is spread across multiple tools, such as Notion, individual onboarding plans, and various Google Docs.
• Product Notion pages are often not up to date and a limited number of Medic colleagues have access rights to suggest updates.
• Every time a developer joins the team, we create a “Technical onboarding” document copy shared only with them.
• From GitLab: “Having a "handbook first" mentality ensures there is no duplication; the handbook is always up to date, and others are better able to contribute.”
• Openness is one of Medic’s values. Sharing the product development process with the community could increase visibility on how we build tools at Medic.

How?

• “Public by default”. Make it accessible to the organization and to the community, “GitLab style”.
• Move the content to GitHub-based documentation. This would allow anyone from the team to suggest changes.
• Living document. Everyone at Medic should be able to contribute to the handbook.
• Keep it simple.

Content ideas

• Why a handbook?
• Team
  • Who we are
  • OKRs
  • Engineering Values (something like this)
  • House Rules (remote calls, communication style - example, being respectful of others time, …)
  • About async work (see GitLab’s guide)
  • People Management
  • Learning
  • Check other ideas here
• Product Development Process
  • Continuous Discovery
  • Focused Groups
  • Product Trio
  • UX Research Repository
  • Quality Assistance
• Developer Tools
  • IDE, version control
• System Design & Architecture
  • Guidelines (Prefer X over Y…) - example
  • Refactoring
  • Design Docs
• Developer Experience
  • Pair programming
  • Onboarding
• Release Engineering
  • Engineering Fundamentals Checklist (e.g. this)
  • Code reviews
  • Automated testing (example)
  • Continuous Integration
  • Continuous Delivery
  • …
• Documentation
  • Architectural Decision Records
• Team Conversations
  • Daily updates
  • Retros
• Appendix
  • Glossary
  • Vital Reading Material
  • Recommended Watching
  • Recommended Reading Links

References

• GitLab Engineering
• GitLab the Remote Playbook
• Atlassian Engineering Playbook
• Obvious Playbook
• Thoughtbot Playbook
• Google style guides
• Microsoft Code-With Engineering Playbook
• Microsoft Guide
• Truss Playbook

I believe that some items (as the ones you mentioned in the description of the ticket) are addressed to the CHT core contributors, and some of them (as team conversations, for example) are addressed to Medic team. Nevertheless, they could both live under the same documentation, "GitLab" style.

@craig-landry I would also move most of the Product Notion pages under this handbook (e.g. Continuous Discovery, Product Trio, etc).

How should we proceed with this? I can foresee several steps, please let me know if you have other ideas:

• Re-organize the pages you mentioned above
• Create a skeleton of pages we want to create
• Start drafting the content
• Involve @esthermmoturi in all these steps.

[garethbowen]

I believe that some items (as the ones you mentioned in the description of the ticket) are addressed to the CHT core contributors, and some of them (as team conversations, for example) are addressed to Medic team. Nevertheless, they could both live under the same documentation, "GitLab" style.

I totally agree with this. At first I felt slightly awkward about including things like our meeting schedules in the CHT docs site, but if it's phrased right then I think it'll be informative to non-Medic readers too.

How should we proceed with this?

I like your list for first steps, presumably done in that order. I'm happy to help or hand off to you, whichever you prefer.

[andrablaj]

You know better the existing documentation and you already have a plan on how to reshuffle pages in a new structure, so please go ahead with the initial changes you suggested when opening the ticket. I can contribute further from there with adding new pages (as needed) and having discussions with the developers on guidelines.
Thanks!

[garethbowen]

The first cut (re-arrange everything) is merged.

@andrablaj I think the best way forward would be to split the rest of the work into individual issues which are more manageable. What do you think?

[andrablaj]

I agree @garethbowen, thanks for raising this.

I believe that some content would fall under "Product/Engineering @ Medic" section. Examples:

• Team: e.g. communication, remote work guidelines
• Continuous Discovery Process
• Quality Assistance & how we do QA @ Medic
• Developer Experience: onboarding (e,g. app services onboarding page ).
  And many other ideas that I shared above.

Do you have a suggestion with what to start with? I am more than happy to start drafting content.

[garethbowen]

@andrablaj Oh those are all great.

1. I'd find a good writeup of CD particularly valuable as we have two FGs onboarding onto the process.
2. Quality Assistance should be next as this is a new concept for most of the team
3. Then onboarding because I don't feel like we have a good story for that right now (after the general Medic onboarding completes)
4. Team - very useful but not as pressing as the other 3 IMO

One thing to keep in mind is this is guidelines for how the CHT community works more broadly than Medic specifically. In some ways that's just a branding change (ie: replace "Medic" with "CHT Community"), but it restricts us to only referring to public resources. We can re-evaluate if this gets too clunky.

[andrablaj]

Happy that we are on the same page! 🙌
I can start putting together the "Onboarding" one, and then the others little by little (and align with the team @esthermmoturi ).
Is there anything else that we should keep in mind? (before going on holidays)

[esthermmoturi]

@andrablaj Nothing on my mind for now. I have been following the conversation closely and will give my input as we go.

[garethbowen]

@andrablaj I think after that if you could look through Notion and migrate anything Product specific you find there to supercharge our openness!

[andrablaj]

Closing the ticket @garethbowen as we should tackle the new Contributor Handbook pages by individual issues, as mentioned here. Happy to have this live. 🥳