Skip to content

Instantly share code, notes, and snippets.

@WebInspectInc
Created June 27, 2016 19:22
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save WebInspectInc/60ed08e3783159d01b5b17415484d0f5 to your computer and use it in GitHub Desktop.
Save WebInspectInc/60ed08e3783159d01b5b17415484d0f5 to your computer and use it in GitHub Desktop.

If you think you want to add something to this documentation, then great! Kudos to you. Documenting your work is good.

But there are a few rules you'll have to follow. We aren’t trying to destroy your fun, but we have specific goals in mind for what should be here, and everything here has to fit those goals. This document should also be reviewed prior to reviewing pull requests that include documentation changes, so everyone is held accountable to these rules.

In a nutshell, all documentation should be (1) useful, (2) easy to read, and (3) easy to maintain. To be more specific:

  • Make sure whatever you're documenting will be used in the future. Not just a one-off thing that no one will touch again. If you aren't sure if it will be used again, just add a comment to your code rather adding documentation here.
  • Make sure anything you add here is grammatically correct. If you're pull requesting documentation, call out grammar errors or spelling errors.
  • For an easier reading experience, write documentation from the perspective of us and our team, and keep to the present. Say "our site" and "we do" over "the site" and "the team does/has done".
  • Make your structure visually compelling. Use a combination of headers, lists, paragraphs, codeblocks, and diagrams if applicable.
  • Keep paragraphs short and to the point. No mind-numbing walls of text in here, please.
  • If it feels appropriate, sprinkle in a little humor. But keep it professional, peeps.
  • Get an editor. Just ask someone on the team for their critique on what you write. Everyone reads differently, and the more eyes and brains you get involved the more accessibile our documentation will be. accessible = good

We also have a few code style rules that you should follow:

  • Stick with CommonMark syntax for your Markdown.
  • <h1> and <h2> elements are generated, so use <h3> and <h4> if you really need another header or two.
  • Err on the side of more white space, it's important to make your source files easy to read too.
  • Use code examples liberally, and with the proper Prism syntax.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment