HomeLearnContributeFundingForumChat
    HomeContributeGovernance and Risk Meetings
    Summaries
    G&R Summary Style Guide
    This guide will help you produce high-quality summaries of Maker's recurring Governance and Risk meetings.
    The most critical part of these summaries is accuracy, readability, and intuitive formatting.

    Table of Contents

    Standard Operating Procedure
    • Getting Started
    • Roles
    • Workflow
    Summary Format Rules
    • The Structure
    • General Rules
    • Header and Spacing Rules
    • Speakers and Discussions
    • Special Language Rules
    • Screenshot Best Practices
    • Tips

    Standard Operating Procedure

    Getting Started

    To become a part of the working group that produces these summaries, please join the Maker Chat and communicate your interest in the #community-development channel. Dai grants are available for contributing!

    Roles

    Producing a summary requires two roles, a Writer and Reviewer.
    • Writer: Takes initial notes, adds screenshots, and fixes notes in post-editing with the recording's availability.
      • Recommended to be done by at least two people, splitting up the work for the complete summary.
      • Multiple writers have the advantage of supporting each other with formatting, screenshots, and quality assurance sections that they are not taking the initial notes on.
      • Writers use the ✋ symbol during live calls to request help from another writer.
    • Reviewer: Sets up the initial working doc, does a full review of the summary, performs quality checks for formatting and semantic errors, and submits the final version of the summary to GitHub and the Forum.
      • Recommended to be done by one person.

    Workflow

    1. Reviewer: Prepares the working doc in HackMD by starting a new note from a template of the summary and sends it to the Writers.
    2. Writer: Joins the Governance Call and begins taking notes.
      • If multiple Writers are 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.
    3. Writer: Skims the working doc and fix any obvious errors once the call concludes.
    4. Writer: Receives a link to the recording of the call a few hours later.
    5. Writer: Completes the summary with the aid of the recording, adding time-anchored-links, adding relevant links, and fixing unclear or unfinished notes.
    6. Writers Notifies the Reviewer that they are finished with the summary.
    7. Reviewer: Performs a full quality-check of the summary.
    8. Reviewer: Submits a single Pull Request to the MakerDAO Community Repository
    9. Reviewer: Submits the summary as a comment on the call's forum thread.

    Summary Format Rules

    The Structure

    This is the general structure of the document. #h refers to the heading type. Headings are useful for standardizing the structure of a 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

    General Rules

    • Summaries are created in HackMD and saved as markdown files(
      .md
      ). The final version is published to GitHub and the Forums, which are both markdown friendly.
    • Filename Format: 
      episode-000.md
    • Notes are chronological.

    Header and Spacing Rules

    Speakers and Discussions

    • The goal of the summary is the accuracy and readability of the content on the call.
    • Notes should be "semi-transcribed." They should only deviate from what was said on the call if it is to fix the note's readability.
    • Minor edits to bridge spoken word to written word are permitted if they respect the semantic information conveyed by the speaker.
    • Do not include "umm," "so," "like," irrelevant tangents, or any other obfuscating language. The summary aims to most clearly capture the main points in a concise and readable fashion.
    • Add an 
      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.
    • Add a 
      `Chat`
      marker to the beginning of questions or comments coming from the chat.
      • Only include insightful comments and questions. Especially include content that is responded to on the call.

    Special Language Rules

    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 the names of people and online handles.
    • Capitalize and use backticks for any specific system parameters:
      • For example: 
        `flop`
        , 
        `bite`
        , 
        `vow`
        , 
        `kick`
    • Do not use backticks when referring to generalized system language.
      • For example: Stability Fee, Debt Ceiling, Debt Auction, Vault ETH-A, MIPs.
    • When referencing material from the summary, please use "below" and "above" language.

    Screenshot Best Practices

    Governance Calls often have visual presentations. The most efficient way to capture these is through screenshots and elaborating notes below the image. 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)
    • Windows: Download Puush or ShareX and create a hotkey for "Region Screenshot."
      • Both of these options 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)
    • OSX: 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.

    Tips

    • Consult the Writing Style Guide and Reviewer Guides for additional information.
    • 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 find missed mistakes.
    • Use a Linter in VSCode to find formatting errors. For more information on linters, see the Contributor Tools Guide.
    • Take readable screenshots.
    • Don't duplicate information already presented on slides. Focus on the additional points made during presentations that include slides.
    • Conversations may be hard to transcribe at the moment, so do your best.
      • Use initials when conversations get fast back-and-forth. It also helps readability.
      • Use bullet points to semantically break apart longer speaking segments, both in presentations and discussions.
      • Add video links to the above individual questions and transition points during the call.
    • Aim to keep notes readable. Always ask, "does this make sense?" Even if the conversation breaks off into a tangent, always try to find the thread.