jonathan@researchcomputingteams.org
This resource first appeared in issue #18 on 03 Apr 2020 and has tags Technical Leadership: Other, Managing A Team: Documentation/Writing, Working With A Research Community: Communications Tools
Design Docs, Markdown, and Git - Caitie McCaffrey
Azure Sphere Security Services used a Word/Sharepoint workflow for drafting, circulating, refining, and approving design documents wasn’t working, so they trialed a move to using markdown and git for their design documents. It was a success, and here they write up their approach.
Not every design document corresponds to just on repository’s worth of code, so they chose to have one single repo for design documents for their organization organization, to support discoverability and large/unconstrained multi-codebase architectural designs.
They used standard github comments for discussion, and pull requests with formal lists of approvers for making changes. Although not every PR requires significant discussion, when they do, review meeting invitations are sent around with a link to the specific pull request being discussed.
One of the biggest benefits I’ve observed is the clarity it has brought to how decisions are made, and durably recording when things are done. On a fast growing team like Azure Sphere having clarity and durable communication are key to successfully scaling the business and the team.
