How to Write (More) Docs
Purpose: The How to Write (More) Docs section provides guidelines on how to extend the documentation of the Design System. It outlines what topics should be covered at both the component and foundations level, emphasizes the importance of clear and consistent vocabulary, suggests the use of illustrations and visual aids to enhance understanding, and highlights the significance of a well-organized information architecture.
What to Cover
Purpose: The What to Cover topic provides guidance on what topics should be covered in the documentation of the Design System. It encourages comprehensive coverage of both individual components and foundational concepts. The goal is to provide users with a complete understanding of how to use and implement the Design System effectively.
When documenting the Design System, consider covering the following:
- Component usage and behavior
- Styling and theming guidelines
- Accessibility considerations
- Design patterns and best practices
- Integration and implementation guides
- API documentation (if applicable)
- Troubleshooting and frequently asked questions
Vocabulary
Purpose: The Vocabulary topic emphasizes the importance of establishing and maintaining a clear and consistent vocabulary throughout the documentation. Using consistent terminology helps users understand and navigate the Design System more effectively.
When writing documentation, adhere to the following guidelines:
- Define and explain key terms and concepts.
- Use consistent terminology throughout the documentation.
- Avoid jargon and technical language when possible.
- Provide clear and concise explanations.
Use of Illustration and Visual Aid
Purpose: The Use of Illustration and Visual Aid topic highlights the benefits of using illustrations and visual aids to enhance the documentation. Visual elements can help users understand complex concepts, provide examples, and improve overall comprehension.
Consider incorporating the following visual aids in your documentation:
- Diagrams or flowcharts to illustrate processes or interactions.
- Screenshots or images to showcase component examples.
- Icons or symbols to represent concepts or actions.
- Color-coded visuals to differentiate between states or variations.
Information Architecture
Purpose: The Information Architecture topic emphasizes the importance of a well-organized documentation structure. An intuitive and logical information architecture helps users navigate the documentation easily and find the information they need efficiently.
When structuring your documentation, consider the following:
- Use a clear hierarchy with sections, sub-sections, and headings.
- Group related topics and components together.
- Provide navigation or table of contents for easy access.
- Use descriptive and concise titles for sections and headings.
References: