For existing components, we have the documentation pages on the Codex docs site, which are partially automatically generated from documentation comments in the code, and partially hand-written with examples. See https://doc.wikimedia.org/codex/main/components/message.html and the other entries in the navigation sidebar under "Components".

In T313917#8110417, @Catrope wrote:

For existing components, we have the documentation pages on the Codex docs site, which are partially automatically generated from documentation comments in the code, and partially hand-written with examples. See https://doc.wikimedia.org/codex/main/components/message.html and the other entries in the navigation sidebar under "Components".

Thanks! A few questions:

• Does this mean that any new component we add will automatically get added here? If so, at what point would that happen?
• Do we support and indicate versions for components? (Given that components may evolve over time)
• We've talked about component variants, is there a logic for how they are handled here
• Is there a reason we don't add the link to the design specs in Figma?

Another inconsistency in the components section is that we don't include an "Overview" section of what the components. Just as we have this for "design tokens" it would be great to add this in the components section.

I'm also noticing that we have some documentation for Codex in 2 places. Thoughts on if we should consolidate?

• https://www.mediawiki.org/wiki/Codex
• https://doc.wikimedia.org/codex/main/introduction/usage.html

In T313917#8113446, @DAbad wrote:

• Does this mean that any new component we add will automatically get added here? If so, at what point would that happen?

It's not automatic, but it is part of our process to add a docs page for each new component. This is documented in the contributing code guidelines, although it will soon be updated to give contributors more options for working with demos (e.g. they add a simple demo in the codex package, then we pair them with a DST developer who will add the full demo page in the codex-docs package)

• Do we support and indicate versions for components? (Given that components may evolve over time)

No, although we have had discussions about what version of the code should be used for the canonical docs site. Right now, the site is based on the main branch, which means as soon as something is merged, it shows up on the docs site. This has caused some confusion for MediaWiki developers, who are working off of the latest release of Codex, not the main branch. T311097 covers this issue.

• We've talked about component variants, is there a logic for how they are handled here

"Variants" is much more critical as a design term than a developer one, since it's A Thing in Figma. That said, we should document standards for how to document components on their demo pages, e.g. when we should build a configurable demo, what separate demos should be included, etc.

• Is there a reason we don't add the link to the design specs in Figma?

I think we should! We need to have a conversation about which users we're supporting on the demo pages, but I personally think we should be supporting all users of Codex (designers, developers, product folks, etc). Right now, the demo pages have the following structure:

• Name of component
• Description of the component. The first sentence should be a brief summary that's not overly technical (we often pull this from the design spec). We sometimes follow this with more technical documentation, but we should probably change this to describe the function/features of the component rather than the implementation, which is covered further down the page. Note that these descriptions are pulled directly from the docblock comment above every component in its .vue file.
• Configurable demo, if applicable
• Other demos that can't be properly demonstrated or explained via the configurable demo. Often these come with brief explanations of how they work.
• Component usage documentation. This is auto-generated from the .vue file and describes how the components work under the hood, and how they can be implemented by other developers.

I think adding a section below the description with the following information would be helpful:

• Link to the Figma spec
• Link to the .vue file of the component on GitHub for now, GitLab later (this can be helpful for developers who want to better understand the component)

In T313917#8113457, @DAbad wrote:

Another inconsistency in the components section is that we don't include an "Overview" section of what the components. Just as we have this for "design tokens" it would be great to add this in the components section.

+1!

In T313917#8113745, @DAbad wrote:

I'm also noticing that we have some documentation for Codex in 2 places. Thoughts on if we should consolidate?

• https://www.mediawiki.org/wiki/Codex
• https://doc.wikimedia.org/codex/main/introduction/usage.html

My impression is that the mediawiki.org page is meant to document MediaWiki-specific stuff related to Codex (and it's standard to have a mediawiki.org page for a library like this). One of the guiding principles of Codex is to build it not only for MediaWiki, but for the wider MediaWiki ecosystem and beyond, so we have aimed to avoid anything MediaWiki-specific within Codex. So, having MediaWiki-specific instructions on the Codex docs site would not be ideal.

All that said, I had forgotten that the Codex mw.org page even existed, so it would be great to clarify its purpose and our strategy for keeping it updated. A lot of the usage info could be moved to the Vue.js docs on mw.org instead.

@EUdoh-WMF brought up a good point today; that the Codex docs site doesn't talk about which version of Codex is currently in MediaWiki. That information probably shouldn't live on the docs site, but on mediawiki.org (it's currently on the Codex page), but we should at least link to docs on using Codex within MediaWiki from the Codex docs site. I'm going to add a point to T313938 to include this.