This is a guide to producing a high quality summary of recurring Governance and Risk meetings at MakerDAO.
TL;DR: The most important part of these summaries is accuracy, readability, and a format that is intuitive for the reader.
Standard Operating Procedure
Summary Format Rules
To become a part of the working group that produces these summaries please join the Maker Chat and mention your interest in the #community-development channel. Dai grants are available for contributing!
Producing a summary requires two roles, a Writer and Reviewer.
Writer: Takes initial notes, adds screenshots, and fixes notes in post-editing with the availability of the recording.
Recommended to be done by at least two people, splitting up the work for the entire summary.
Multiple writers have the advantage of supporting each other with formatting, screenshots, and quality assurance on sections that they are not taking the initial notes on.
Writers use the
:hand:(:hand:) symbol during live calls to request help from another writer.
Reviewer: Sets up the initial working doc, does a full review of the summary after it's produced, quality checks for formatting and semantic errors, and also submits the final version of the summary to GitHub and the Forum.
Recommended to be done by one person.
Reviewer: Prepares the working doc in HackMD by starting a new note from a template of the summary and sends it to the Writer(s).
Writer(s): Joins the governance call and begins taking notes.
If there are multiple Writers doing the summary, they should decide amongst themselves which sections they are taking notes on.
Communication between writers can happen in the working doc or through a separate chat group.
Writer(s): Skims the working doc and fix any obvious errors once the call concludes.
Writer(s): Receives a link to the recording of the call a few hours later.
Writer(s): Completes the summary with the aid of the recording, adding time-anchored-links, adding relevant links, and fixing unclear or unfinished notes.
Writer(s): Notifies the Reviewer that they are finished with the summary.
Reviewer: Performs a full quality-check of the summary.
Reviewer: Submits the summary as a comment on the call's forum thread.
This is the general structure of the document. #h refers to the heading type. Headings are very useful for standardizing the structure of this summary.
#h1 Title: Ep00: Month 00, 0000├ ##h2 Agenda├ ##h2 Video├ ##h2 Main Theme (MIPs, Risk, Oracles, Smart Contracts, etc.)| └ ###h3 Name of person presenting| ├ #####h4 Segment Description| └ ######h5 Sub-Segment Descriptions| └ #####h4 Discussion 1├ ##h2 Main Theme (Risk, Oracles, Governance, etc.)| └ ###h3 Name of person presenting| ├ #####h4 Segment Description| └ ######h5 Sub-Segment Descriptions| └ #####h4 Discussion 2├ ##h2 Ending Discussion├ ##h2 Links from the Chat├ ##h2 Terms├ ##h2 Credits
These summaries are created in HackMD and are saved as markdown files(
.md). This is because the final version is published to GitHub and the Forums, which are both markdown friendly.
Notes are taken in chronological order.
Headers follow the rules in the structure displayed above and occur chronologically.
The same "Main Theme" can occur more than once, but must be numbered, similar to the discussion section headers.
Include line breaks above and below headings.
Include time-anchored-links in the Agenda.
Include time-anchored-links under "Segment Description" headers.
Include time-anchored-links every 5 minutes or so for individual questions and comments during the discussion segments.
Include line breaks above and below time-anchored-links.
Include line breaks above and below screenshots and their relevant notes.
Do not leave trailing spaces.
Ensure there is a single empty line, called a hard-return, at the end of the file.
The goal of the summary is accuracy and readability of the content on the call.
Notes should be "semi-transcribed"; meaning they only deviate from what is originally said if it is to fix the readability of the note.
Minor edits to bridge spoken word to written word are permitted and should respect the semantic information being conveyed by the speaker.
Do not include "umm", "so", "like", irrelevant tangents, and any other obfuscating language. The aim of the summary is to most clearly capture the main points in a concise and readable fashion that is semantically true to how the point was spoken.
h4 Discussion header at the end of each section if there are questions or comments.
If there are no questions or comments, do not include a Discussion header.
`Chat` marker to the beginning of questions or comments coming from the chat.
Only include insightful comments or important questions. Especially include content that is responded to on the call.
In standardizing the rules around contributing, the community maintains a writing-style-guide that contains all the rules for consistent language, grammar, and formatting. Below are the rules most relevant to these summaries:
Please follow the Naming Convention guidelines found in the writing style guide.
Use short, concise sentences. The balance is to use the least words for the most accurate and comprehensive coverage of what the speakers are saying.
Use oxford commas.
Capitalize names of people and online handles.
Capitalize and use backticks for any specific system parameters:
`kick` , etc.
Do not use backticks when referring to generalized system language.
For example, Stability Fee, Debt Ceiling, Debt Auction, Vault ETH-A, MIPs, etc.
When referencing material inside the summary itself, please use "below" and "above" language.
The Governance Calls often have visual presentations. The most efficient way to capture these is through screenshots, and add elaborating notes below the image if necessary. The recommended software below should keep the last screenshot in your clipboard as a copied image. In HackMD, pasting copied images will automatically upload them to Imgur and provide an embedded link for you([see example.]())
For Mac: Katana is a simple, open-source screenshot utility for macOS that lives in your menu-bar.
Katana does 90% of what ShareX can do, but it's Imgur link needs formatting in HackMD after pasting.
Read for clarity before rewatching. While doing so, edit for low hanging fruit: readability, spelling or grammar mistakes, and formatting errors.
Rewatch at a comfortable playback speed; speeds up to 2x are available on YouTube.
Use tools like Grammarly to help you find missed mistakes once you are done with your section.
Use a Linter in VSCode to find formatting errors. For more information on linters, consult the Contributor Tools Guide
Take screenshots that are readable.
Don't duplicate information already presented on slides. Focus on the additional points being made during presentations that include slides.
Conversations may be hard to transcribe in the moment so do your best.
Use initials when conversations get fast back-and-forth. Also helps readability.
Use bullet points to semantically break apart longer speaking segments, both in presentations and discussions.
Add video links to above individual questions and transition points during the call.
Aim to keep the notes readable. Always ask "does this make sense?" Even if the conversation breaks off into a tangent, always try to find the thread.