Skip to main content

Contributor Tools

This Guide introduces the tools used by the Yearn Community team and its contributors.

Yearn contributors work with tools geared towards promoting open-source feedback, communication, transparency, and clarity. While there is no sophisticated software stack, contributors should be comfortable with the more heavily used tools and how they function within Yearn contribution workflows.

Discussion Platforms​

Discord​

Various Yearn teams (documentation, development, etc.) host AMAs, ideation, discussions, and follow-ups on Yearn's Discord Channel, an open-source platform geared towards improving team communication. The Yearn Discord lists all channels and users.

Start participating in public discussions by joining the recommended channels below.

Pro Tips:

  • Visit #documentation regularly.
    • It's an excellent channel for collaboration.
  • Coordinate with other members.
  • Share early and share often.
  • Ask for feedback.
  • Provide progress updates.

Meetings​

Yearn contributors host meetings when necessary on Google Hangouts. These are not centrally organized and arise organically within discussions between contributors or teams, as such, invitations are up to the individuals organizing these discussions. Invitations are sent to contributors by Discord or Telegram and Google Calendar automatically schedules the event and sends reminders.

Writing Platforms​

HackMD​

Many Yearn Doc contributors prepare their long-form documentation in HackMD, a collaborative Markdown editor. HackMD also tracks versions, enables commenting, and allows multiple users to work on a document simultaneously.

Note: Run all drafts through Grammarly regularly, and before final submissions.

  • Grammarly will catch most spelling and grammatical errors.
    • Review the suggestions to make sure they make sense.
    • Do not blindly accept Grammarly edits.
  • HackMD does not identify spelling and grammatical errors.
    • Copy text from the rendered preview into Grammarly and address any errors it flags.
    • Grammarly will miss errors if it’s given raw Markdown text.

Pro Tip: Install the HackMD Google Chrome extension to make searching easier.

Google Docs​

Google Docs is a collaborative writing platform, with features like suggestion editing and version naming. Docs simplify feedback and review and are easy to share between team members and contributors.

Suggestions:

  • Start new projects and create first drafts in Google Docs.
  • Use "Suggesting Mode" and leave "Notes" when reviewing a document.
    • Suggestions draw attention to proposed changes.
    • Notes leave room for side discussions.
  • Avoid including direct links in a Google Doc.
    • Use the Markdown format to simplify conversion later on.
      • Incorrect: https://bad.link.com
      • Correct: [link](https://link.com)
  • Versions can be named, renamed, downloaded, or revisited at any time.
    • Versions help other contributors quickly find and see any changes.
      • Example: Naming a Version
  • Make sure to name versions before passing projects off for review.
    • Use descriptive names for versions.
      • Names should contain information specific to the contents of the file or version.
  • Include a version number in the name, along with any other relevant details.
    • Numbers after the decimal define draft iterations.
      • Example: V0.1, V0.2, V1.2, etc.

Markdown​

Yearn documents hosted on GitHub are written in Markdown, a plaintext formatting syntax. Markdown allows for easy conversion to HTML and various other outputs, making documents easy to read on the web.

The markdown files are compiled with Docusaurus to bring you the styled documentation UI you see here.

VSCode​

If you are using Google Docs to write, consider using Visual Studio Code and install the extensions below to facilitate formatting:

  • Markdown Preview Enhanced
  • Markdown Linter
  • Code Spell Checker
  • GitLens
  • Prettier
    • Prettier will auto-correct most Markdown mistakes.
  • The vscode-markdownlint GitHub repo describes how to edit the error settings JSON file.
    • Use it to address any Markdown errors that follow the Writing Style Guide.
  • How to integrate GitHub with VSCode:

Tools and Tips​

Writing Specific​

Best Practices​

  • Include line breaks above and below headings.
  • Use top-level headers # only once per document.
    • Do not make multiple top-level headings.
  • Avoid repeat headings.
    • They will break auto-generated navigation.
  • Avoid trailing spaces.
  • Do not use:
    • Em or en dashes: —.
    • Ampersands & in titles and headers.
    • Pipes | in titles and headers.
    • Curly quotes. Use the plaintext version.
      • Correct: "
      • Incorrect: “
    • Escaping parentheses. Use normal parentheses.
      • Correct: (SOMETHING)
      • Incorrect: \(SOMETHING\)
  • Add tasks using check-boxes as projects grow.
    • A dash and brackets (- []) on a new line show up as a checkbox in GitHub's UI.
    • Example:
      • [ ]
  • Ensure there is a single hard return at the end of a .md file.
  • Use in-text comments for extra visibility when collaborating with other contributors on HackMD documents.
    • Click on the comment icon in the toolbar and choose an appropriate style.
    • Consider including a timestamp or username:
      • Markdown: > Look Here! [name=John Doe]
      • Rendered: Look Here! \[name=John Doe\]
    • Make sure to delete comments before submitting Pull Requests.
  • Use an emoji to call attention to an important point, when necessary.
    • Practice discretion and use them sparingly.
      • Do not load documents with emojis.
    • This cheat sheet lists emojis and their Markdown shortcuts.

Naming Files and Versions​

  • Markdown file names should be lowercase.
  • Use dashes -, not spaces, to separate words within Markdown file names.
    • Correct: meeting-transcript-ep-01.md
    • Incorrect: Meeting Transcript Episode 01.md
  • Use descriptive names for Markdown files and versions.
    • Filenames should contain information specific to the contents of the file.
      • Context is provided from the directory or through the presentation layer (e.g., Docusaurus).
    • Correct: meeting-summary-ep-01.md
    • Incorrect: scientific-governance-and-risk-meeting-summary-ep-01.md

Pro Tip: For a document's final draft, name it "Final draft, moving to GitHub." Post a link to the HackMD file or a relevant page on GitHub.

Miscellaneous​

Wallets and 3rd Party Services​

  • Metamask: Wallet for sending and receiving YFI
  • Zerion: For checking Yearn Treasury statistics.

Keyboard Shortcuts​

Acknowledgments​

This document could not be possible without the amazing work done by the MakerDAO team as this document is mostly based on their Contributor Tools Guide.

Last updated on