Learning resources

• https://www.oreilly.com/content/the-eight-rules-of-good-documentation/

  1. Write documentation that is inviting and clear
  2. Write documentation that is comprehensive, detailing all aspects of the project
  3. Write documentation that is skimmable
  4. Write documentation that offers examples of how to use the software
  5. Write documentation that has repetition, when useful, DRY otherwise.
  6. Write documentation that is up-to-date
  7. Write documentation that is easy to contribute to
  8. Write documentation that is easy to find

• https://documentation.divio.com/

  

Audience

• We support all users, from beginners to experts.

• We write in en-US *(*no en-GB, etc.).

• We target an 8th-grade US reading level. Why

  

• Most people don’t read.

  

  https://twitter.com/sarah_edo/status/1530272066808598529

  Optimize the content to be skim-read. How? First by having a great heading structure.

Linting

• Grammarly is a great way to fix language issues.

Guidelines

1. Only use "we", "our" for recommendations.

   -We expose a `disableRipple` prop to remove the ripple.
   +The button exposes a `disableRipple` prop to remove the ripple.
   

2. Sentence case, the upper case is the first letter of the title, not the others (per Capitalization) e.g.:

   -## Customization Demos
   +## Customization demos
   

3. The name of a component in the header is in the singular when possible, e.g.:

   -## Buttons size
   +## Button size
   

4. Boolean props should be in the present tense. (https://github.com/mui-org/material-ui/pull/23274). e.g.:

   -If `true`, the accordion will be displayed in a disabled state.
   +If `true`, the accordion is displayed in a disabled state.
   

5. In the context of React: “properties” → “props”. In other contexts, use “properties”.

6. HTML “attribute” ≠ “property”.

7. When linking pages:

   • Make sure the link you point to has a 200 HTTP status.

     -find [more details](/api/appbar/) about the API
     +find [more details](/api/app-bar/) about the API
     

   • The documentation is not guaranteed to stay under the naked domain. Use relative paths when the content is linked to the version of the software the developer is using, e.g.

     -find [more details](<https://mui.com/api/app-bar/>) about the API
     +find [more details](/api/app-bar/) about the API
     

   • Use an absolute path when the content should stay evergreen, e.g.

     -comparison is available on the [Pricing](/pricing/) page.
     +comparison is available on the [Pricing](<https://mui.com/pricing/>) page.
     

8. Over time, pages might grow up to the point of being overwhelming. Split a page when at least one of these conditions is true:

   1. over 10k pixels
   2. the TOC has a scrollbar (on a 13” screen)
   3. the feature is important “enough” on its own.