Documentation is a significant part of Codex, our new toolset for building UIs within the Wikimedia Design System. This task captures an overview of the documentation we intend to add to the library initially.

Sections

README

This covers the README in the root of the repository.

Proposed contents

• Description of the library
• Link to the live demo site
• Quick start, link to usage docs
• Intro to contributing, link to contributing docs
• Important links (Phab, DST team page, etc)

---

Introduction

Proposed outline

• About: This is the landing page of the docs site, and will describe what the library is, provide links to usage and contributing information, list maintainers and contact info, and cover guiding principles.
• Getting started: This page will describe how to get started using the library (installation, component and design token usage, etc.)

---

Contributing

Since the new component library will be collaboratively built and open to contributions from a wide variety of people, we need clear guidelines for how to contribute. WiKit and WVUI both include contributing guidelines, with WiKit's being more comprehensive to an entire design system and WVUI's being focused on the contribution and review of code.

Considerations

• Display the contributing docs in the online demo tool, like WiKit has done by including their contributing docs in their Storybook demo (see links below)
• Carefully consider docs structure so people can find what they need quickly
• Keep documentation as concise as possible, so people will actually read it
• Keep documentation warm, accessible, and easy to read to encourage contributions. Don't assume too much knowledge and keep things non-technical when possible (docs about how to actually write code in the library will be separate)
• Consider all the ways to contribute, including design, development, feedback, and documentation

Proposed outline

These are the pages that would live under a "Contributing" heading in the docs:

• Guidelines
  • State our intention to welcome contributions from anyone who’s interested, across roles and levels of experience.
  • Explain the different ways to contribute (design, development, feedback, and documentation)
  • Include links to communication channels and Phab board(s); explain how to stay up-to-date
  • General conduct for contributing/link to CoC
• Designing components
  • Info for designers and links to design resources, introduce the hybrid approach [1]
• Contributing code
  • Author guidelines
    • How to add/track tasks
    • Patch requirements (with links to relevant bits of the developer docs)[2]
  • Developing
    • All the technical details of how to write code in the library

[1] The hybrid approach refers to the vision for component governance that involves both the Design Systems team and other stakeholders (WMF product teams, WMDE, volunteers, etc.) contributing to the design system. While a new component may start as a proposal for a certain product, the governance model includes evaluating whether the component should be added to the design system, determining who will drive the design and development work, and getting review from stakeholders across teams. We believe this is the most sustainable and effective model for the maintenance and development of the Design System.

[2] Patch requirements should reflect the criteria listed in the component governance model, see the "Test component/pattern" step and T288710

Relevant links

• Wikit's contributing guidlines: contributing, modifying existing components, creating new components
• WVUI's contributing guidelines: CONTRIBUTING.md

---

Design tokens

Proposed outline

• Introduction to design tokens (what are design tokens, link to how to use them, link to how to modify or add them (note: if this is covered elsewhere, the intro in the design tokens section isn't needed)

---

ADRs

This section will capture architecture decision records.

Proposed outline

• Introduction to ADRs, what they are, why we record them, how we intend to record them moving forward
• One page per ADR

---

Acceptance criteria

Docs to write

• README
• Introduction -> About
• Introduction -> Getting started (usage)
• Contributing -> Guidelines
• Contributing -> Designing components
• Contributing -> Contributing code
• Design tokens -> Introduction
• ADRs -> Introduction
• ADRs -> At least one example ADR

Criteria to cover

• Add or link to code of conduct
• Link to existing contributing guidelines on mediawiki.org
• Make sure patch requirements includes a description of the component in the docblock, since this shows up on the demo page
• Make sure it's clear where to go to ask questions or give feedback about different parts of the library
• Answer the question "what am I able to do with this library?" and include in the intro
• Emphasize that components are built with Vue 3
• Include in the intro what makes the library special (i18n coverage, a11y support baked in, etc.)