Skip to content

Latest commit

 

History

History
70 lines (49 loc) · 3.76 KB

dev-article-styleguide.md

File metadata and controls

70 lines (49 loc) · 3.76 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 is free of all text related to document instructions, such as \<your platform\> or \<insert your code here\>

  • Your document has metadata in the top comment of the file that contains the appropriate information for your platform's component

  • Your document uses the – ('&ndash;') and not — ('&mdash;')

  • All components (all elements, images, videos, icons, any other critical graphical element) are labelled correctly for screen reader use (see the greenlines for elements for more details on what to include in your labels)

  • Your document's images of text have correct screen readable labels

  • Your document's hyperlinks communicate their destinations in text

  • Your document uses Nomenclature is consistent throughout the application (and Google) (e.g. “Delete” and “Erase” should not both exist.)

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