|
| 1 | +--- |
| 2 | +name: Write Component Documentation |
| 3 | +description: Generates wiki documentation for new DIPS.Mobile.UI components following established patterns and conventions. |
| 4 | +--- |
| 5 | + |
| 6 | +# Write Component Documentation |
| 7 | + |
| 8 | +When asked to write documentation for a new component, generate a `wiki/<ComponentName>.md` page following the template and rules below. |
| 9 | + |
| 10 | +## Trigger Phrases |
| 11 | + |
| 12 | +- "Document this component" |
| 13 | +- "Write wiki page" |
| 14 | +- "Add documentation" |
| 15 | +- "Create wiki doc" |
| 16 | + |
| 17 | +## Before Writing |
| 18 | + |
| 19 | +1. **Read the component source code** — understand all public properties, bindable properties, events, commands, and options classes |
| 20 | +2. **Check for sub-components or variants** — e.g., `NavigationListItem` alongside `ListItem`, `FilledCheckBox` alongside `CheckBox` |
| 21 | +3. **Check for platform differences** — look at iOS/Android partial classes for behavioral differences |
| 22 | +4. **Check accessibility support** — does the component set semantic properties, use `TouchPlatformEffect`, or have accessibility-specific features? |
| 23 | +5. **Look at the sample app** — check `ComponentsSamples/` or `AccessibilitySamples/` for usage examples |
| 24 | + |
| 25 | +## Template |
| 26 | + |
| 27 | +Use the following structure. Sections marked **(if applicable)** should only be included when relevant. |
| 28 | + |
| 29 | +```markdown |
| 30 | +<Short description of what the component is — 1-2 sentences. Written before any heading. Explain the purpose and when to use it.> |
| 31 | + |
| 32 | +# Inspiration **(if applicable)** |
| 33 | + |
| 34 | +<Links to design guidelines that inspired the component, e.g., Material Design, Apple Human Interface Guidelines.> |
| 35 | + |
| 36 | +# Usage |
| 37 | + |
| 38 | +<XAML example showing the most common/basic usage of the component.> |
| 39 | + |
| 40 | +> <Any important notes about defaults, required properties, or common gotchas.> |
| 41 | +
|
| 42 | +# Styles **(if applicable)** |
| 43 | + |
| 44 | +<List available styles/variants with a brief description of each.> |
| 45 | + |
| 46 | +# Tips and tricks **(if applicable)** |
| 47 | + |
| 48 | +<Practical guidance: recommended patterns, common combinations with other components, or things to watch out for.> |
| 49 | + |
| 50 | +# Accessibility **(if applicable)** |
| 51 | + |
| 52 | +<How the component behaves with VoiceOver/TalkBack. Any required semantic properties. Special accessibility features.> |
| 53 | + |
| 54 | +# Properties |
| 55 | + |
| 56 | +Inspect the [components properties class](<GitHub URL to .Properties.cs file>) to further customise and use it. |
| 57 | +``` |
| 58 | + |
| 59 | +### Sub-Component Pattern |
| 60 | + |
| 61 | +When the component has variants or related sub-components, add them as `##` sections after the main component, each with their own `### Usage` and `### Properties`: |
| 62 | + |
| 63 | +```markdown |
| 64 | +## SubComponentName |
| 65 | + |
| 66 | +<Brief description of the sub-component.> |
| 67 | + |
| 68 | +### Usage |
| 69 | + |
| 70 | +<XAML example> |
| 71 | + |
| 72 | +### Properties |
| 73 | + |
| 74 | +Inspect the [components properties class](<GitHub URL>) to further customise and use it. |
| 75 | +``` |
| 76 | + |
| 77 | +## Writing Rules |
| 78 | + |
| 79 | +### Intro |
| 80 | +- Start with a plain-text paragraph **before any heading** — describe what the component is and when people would use it |
| 81 | +- Keep it to 1-2 sentences |
| 82 | + |
| 83 | +### Usage Sections |
| 84 | +- Always include at least one XAML code block with `xml` as the language tag |
| 85 | +- Use the `dui:` XML namespace prefix — do not show `xmlns` declarations (readers already know this) |
| 86 | +- Show the simplest working example first, then more advanced configurations |
| 87 | +- If C# code-behind is needed (e.g., ViewModel bindings, event handlers), include it after the XAML block using `csharp` as the language tag |
| 88 | + |
| 89 | +### Properties |
| 90 | +- Always link to the `.Properties.cs` file on GitHub: `https://github.com/DIPSAS/DIPS.Mobile.UI/blob/main/src/library/DIPS.Mobile.UI/<path>/<Component>.Properties.cs` |
| 91 | +- Use the standard phrasing: *"Inspect the [components properties class](URL) to further customise and use it."* |
| 92 | +- This should be the **last section** (or last sub-section per component) |
| 93 | + |
| 94 | +### Callouts |
| 95 | +- Use blockquotes (`>`) for notes, warnings, and platform-specific differences |
| 96 | +- Bold the callout type: `> **NB!**`, `> **NOTE:**`, `> **Important:**` |
| 97 | +- Use callouts for: default values, platform differences (iOS vs Android), UX warnings, required configurations |
| 98 | + |
| 99 | +### Style |
| 100 | +- Use `#` (h1) for major sections |
| 101 | +- Use `##` (h2) for sub-components |
| 102 | +- Use `###` (h3) for sections within a sub-component |
| 103 | +- Be concise — developers scan documentation, not read it cover-to-cover |
| 104 | +- Write in present tense: *"The component displays..."* not *"The component will display..."* |
| 105 | +- Address the reader as *"you"*: *"Use this when you need..."* |
| 106 | +- Refer to end-users as *"people"*: *"People can tap to..."* |
| 107 | + |
| 108 | +### What NOT to Include |
| 109 | +- No namespace/xmlns declarations (unless the component requires a non-standard namespace) |
| 110 | +- No installation or NuGet instructions |
| 111 | +- No `_Sidebar.md` references — it is auto-generated |
| 112 | +- No Figma links (designers maintain those separately) |
| 113 | +- Do not document internal/private APIs — only public-facing properties and usage |
0 commit comments