HomeLearnContributeFundingForumChat
    HomeContributeContent
    Contributor Tools
    Contributor Tools

    This Guide introduces the tools used by the MakerDAO Community Development team and contributors.

    The Community Development (Comm-Dev) team works 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 serve Comm-Dev.
    Before starting work on a Community Development project, contributors are encouraged to study MakerDAO’s contributor resources.

    Discussion Platforms

    Rocket.Chat

    The Community Development team hosts discussions and follows-ups on MakerDAO's Rocket.Chat, an open-source platform geared towards improving team communication. The main directory lists all channels and users.
    Start participating in public discussions by joining the recommended channels below.
    Pro Tips:
    • Visit #community-development regularly.
      • It's an excellent channel for collaboration.
    • Coordinate with other members.
    • Share early and share often.
    • Ask for feedback.
    • Provide progress updates.

    Meetings

    The Comm-Dev team hosts meetings on Google Hangouts and Zoom. Invitations are sent to contributors by email. Google Calendar automatically schedules the event and sends reminders.

    Writing Platforms

    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.
    • 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.
    • 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.

    HackMD

    MakerDAO prepares its 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.

    Markdown

    MakerDAO 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.

    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 check-box 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., GitBooks).
      • 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.

    VSCode

    • Consider using Visual Studio Code and install the extensions below:
      • 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 (e.g., headers in G&R summaries).
    • How to integrate GitHub with VSCode:

    Miscellaneous

    Important Links

    Wallets and 3rd Party Services

    Keyboard Shortcuts