Skip to content

Latest commit

 

History

History
65 lines (44 loc) · 3.01 KB

dev-article-styleguide.md

File metadata and controls

65 lines (44 loc) · 3.01 KB
Raw

Usage Document Checklist

This is a checklist for developers to ensure that their usage documents maintain stylistic and content standards.

  • Your documentation's tone, language, grammar, and images follow the Google developer documentation style guide highlights.

  • Your document uses the language platform-specific language ("dependencies" vs "installs" for instance)

  • Your document uses the – ('–') and not — ('—')

  • Your documentation meets accessibility guidelines for image alt text.

  • Your documentation uses the canonical component name from the guidelines.

    Description

    Use the name used in material.io/components/<component> instead of the API name for the platform. Reference the platform API name only when referencing the API.

    For example, buttons:
    'Text button' is the canonical name, but FlatButton is the API name in Flutter. When describing the component or component type in the text, use 'text button' and use FlatButton only in either the API references or code samples.

  • Your documentation uses the same component terminology as the guidelines.

    Description

    Aside from API variables and parameters, use the terminology from the component guidance pages.

    For example, chips:
    The chips guidance describes the use of 'thumbnails' and 'remove icon' images/icons. However, the chips article for the web uses the terminology 'leading' and 'trailing' to describe the same images/icons.

    Because this documentation is focused on examples resembling those found in the guidance for material.io/components, use the terminology in the guidance.

  • Your document includes all the component types listed in the guidelines.
    You must include all types, including those not supported by the platform. Any types not supported by the platform should be mentioned as 'unsupported'.

    Example

    The buttons component has 4 types:

    • Text button
    • Outlined button
    • Contained button
    • Toggle button

  • The first word of all heading titles are capitalized and the remaining words in the title (aside from proper nouns or APIs) are lower-case.

  • All instances of API names and API attribute names use ` or \<code\> tags.

  • All code samples use ```<language>.

    Example

    ```html <head>
         <link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons"\>
    </head>
    ```