Note-Taking Formatting Guide
This is the general structure of the document. #h refers to the heading type. Headings are very useful for consistent structuring of the summary.
#h1 Title: Ep00: Month 00, 0000 ├ ##h2 Agenda ├ ##h2 Video ├ ##h2 Main Theme (Risk, Oracles, Governance, etc.) | └ ###h3 Name of person presenting | ├ #####h4 Specific Subject | └ #####h4 Discussion & Questions 1 ├ ##h2 Main Theme (Risk, Oracles, Governance, etc.) | └ ###h3 Name of person presenting | ├ #####h4 Specific subject | └ #####h4 Discussion & Questions 2 ├ ##h2 General Questions and Discussions ├ ##h2 Relevant Resources and Links mentioned in the call ├ ##h2 Terms ├ ##h2 Credits
- These summaries are created in HackMD and are saved as markdown files(
). This is because the final version is published to GitHub and the Forums, which are both markdown friendly.
- Filename format:
- Notes are taken in chronological order.
Header and Spacing Rules
- Headers follow the rules in the structure displayed above and occur chronologically.
- The same "Main Theme" can occur more than once.
- Include line breaks above and below headings.
- Include time-anchored-links in the Agenda, under the "Specific Subject" section, and for individual questions and comments during the discussion portions.
- Include line breaks above and below time-anchored-links.
- Do not include a line break between a screenshot and its relevant notes(see example.)
- Do not leave trailing spaces.
- Ensure there is a single empty line, called a hard-return, at the end of the file.
Speakers and Discussions
- The goal of the summary is accuracy and readability of the content on the call.
- There is no need to transcribe every word.
- Capture presentations and conversations as concise points. Do not include "umm", "so", "like", irrelevant tangents, and any obfuscating language. The aim of the summary is to capture the main points in a concise and readable fashion.
- Always add a Discussion segment at the end of each section to capture questions and comments made during that part of the call.
- Delete the Discussion section if there is nothing to put there.
- Use backticks to add a
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.
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 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:
- For example,
- Do not use backticks when referring to generalized system language.
- For example, Stability Fee, Debt Ceiling, Debt Auction, Vault ETH-A, etc.
- When referencing material inside the summary itself, please use "below" and "above" language.
Screenshot Best Practices
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.]())
- 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 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.
- Try to use bullets to highlight the main conversation question. Add a video link to the initial question or main point for easier reference.
- Aim to keep the notes readable. Always ask "does this make sense?" Even if the conversation tangents away from it's inspiration, you can always find the thread. Keeping it readable is key.