(this page was created automatically. In case of formatting issues, please visit the official Wiki Page)
Page Template
This page will give a systematic guide on the structure and required content of component-pages in this Wiki. Furthermore, it will outline rules on the formatting of text and images.
Structure
Overview
The overview will give a short introduction using four to five bullet points.
- Defines the primary purpose of the component
- Highlights main types or variations (if available)
- Lists the most important features and capabilities
- Notes limitations or constraints
In addition to the bullet points, the overview includes a picture showing of the most important variations and possibilities for the component.
Specs
The Specs have sections with sub headers (h3) explaining every possibility to edit the component. Each section has at least one picture detailing the terms referenced during the section. The text may also include the relevant code for the element. The main sections include:
- Tokens: a table of all usable tokens and a short description of their effect
- Structure & Layout: measurements, spacing, adaptive layout variation
- Styling: color, custom measurements
- Actions & Variants: interaction, transitions, variants
- Testing: automated testing
Not every component needs every section. Conversely, a new section can be created if necessary. Each section can include subsections (using Headings (h4) for clarity) if plausible.
Guidelines
- Explains how the component should be used correctly in different contexts
- Provides rules and best practices for application
- Includes Do’s and Don’ts to prevent misuse
- Must feature visual examples with correct and incorrect usage clearly marked
Accessibility
(in development)
- Protocol of implemented accessibility measures
- Practices to improve accessibility
General Rules
- Sentences should be short and use easy language.
- Repetition of information should be avoided. A detailed description should exist only once and further mentions should be short and relevant to the situation.
- A listing of information during a paragraph should use bullet points instead of text.
- Information should always be accompanied by a picture visualizing the information.
- An Image should be labeled if they give information that is not described in the text accompanying it.
Tags, Notes, other Accessories
The Documentation has 4 types of tags: draft, new, old, updated.
Draft
A page with this tag has content that is actively in development or unfinished. Therefor the published arcticle is currently unfinished. Following szenarios might apply:
- The item of the page, for example a component, is currently in its initial development.
- Information in an article, for example a pattern, is being reworked and thereby subject to change.
- A page in the wiki is being created and the published version is not the desired final state.
A note at the beginning of an article can explain what the development in question is referring to.
New
After a pages first creation it recieves the tag "new". This tag vanishes after two months of being present.
Updated
After recieving significant changes in the content, a page recieves the "updated" tag. This tag vanishes after one month. Significent pages include but are not limited to:
- Addition - New information is added to the page. For example, a component has a new feature.
- Deletion - Outdated or wrong information gets removed from a page.
- Alteration - Information on the page is fundamentally changed. For example, a pattern is restructured. This does not include purely editorial changes.
Coution
If a page contains critical content, it recieves the "Caution"-tag. This applies to both the text and the information behind it. Examples for critical information:
- A page shows outdated information that might mislead the user.
- The subject of the page, for example a component, is not working as designed and needs to be changed.
- Infomration on a page is not verified.
- Multiple users have reported problems with this page.
