Define a component documentation template for the site

[shinytoyrobots]

We need a reusable template that can be followed for providing usage guidance on all components.

This template will also need to be published and usable by any partners or satellite teams, so that we can start building consistency in component documentation regardless of the originating creator of that component.

1044 is dependent on the completion of this issue.

### Tasks
- [x] Define a component doc template

[JohannaJoergensen]

Feb 17 - open pr - James addressing feedback right now - hope to merge today/latest Monday Feb 16 - reviewed doc template; aim to have doc for review soon. Feb 15 - Sion is putting together a markdown template in the format required to produce a component doc template by Friday. Work in progress PR - on track to finish by end of week.
2/14 - designs still in progress; component template regroup on Thursday 2/13 - still working on design 9 Feb - reviewed docs per Shey's additions, set up lucid board to address coming up with mission statement 7 Feb - team will pin down the structure of the page content and visuals 6 Feb - work in progress; confluence page shared with team for review/feedback

[shinytoyrobots]

Adding the email discussion thread (which should really be occurring in Github!)

From @sion-docs...

Things to consider:

• Docusaurus capabilities – What opportunities/restrictions does Docusaurus offer us in terms of navigation/presentation etc.?
• Competitor research – What are the industry trends? How can we stand out?
• Deficiencies – Where are the gaps in the current offering? How can they be filled?
• Roles and responsibilities – Who does what and in what order.
• Research opportunities – How can we make the most of the research we have already done, and what opportunities are there to gather more feedback/data?
• Anything else? Please suggest any items for the agenda

[shinytoyrobots]

From @shey-v

An update form my end. As a follow on from Sions component template, shared yesterday, I’ve been tweaking some initial wireframes (with an aim to place in dummy copy early next week to visualise this better). Sion and I are collaborating on this.

After speaking with consumers from the DXD Markets and Payments teams as well as developers who use the UITK, I’ve refined what to include in our ‘component documentation site template’. As you mention below, this can be used internally with our own team and various LOBs as a starting point to create component docs and keep things consistent.

This current structure is outlined on confluence internally, and has been shaped by consumer feedback documented here in Figma. I’m speaking to a couple more users on Monday in the MTK team so this may alter slightly. I’m currently working on other page layouts and variations at a wireframe level and looking forward to sharing this early next week in our next components regroup.

[shinytoyrobots]

From @shinytoyrobots

Will some of those design alternatives look at options that don’t include the right hand sub-nav? I sometimes worry that it compresses the rest of the main page content too much.

[shinytoyrobots]

From @shinytoyrobots, @bhoppers2008, various...

Apologies if this is premature but a few questions/observations:

1. Love the live examples, but should density and theme switches apply globally? Is this the right place for them? Undecided, this was just one idea. So, in this example I’ve deliberately put them in the ‘live examples’ section because we haven’t yet got a dark theme site yet, only the live examples would change theme/density - instead of other static imagery we may include on the page, i.e. a header image or the anatomy diagrams for example. If we do go with a similar placement to this, we can monitor the usage and see if we need to change the position of the toggles if it is confusing for our consumers. I have also considered placing them at the top underneath our app header (as we currently do on the UITK site) in another example. There’s space at the top of the side nav, above the filter, that could be taken advantage of? Now that we’ve got light/dark icons, it might be possible to make more compact controls and free up space?
2. I’d love to know if ‘Contains’ is actually useful information? We introduced it for the second version of comp pages but do we know if people actually refer to it? If api isn’t exposed, a link to a contained component seems redundant… From speaking with consumers, particularly designers, they feel it is useful and they use it in their Figma libraries/files quite a bit. Some designers refer to components differently, i.e. banner / notification / notification bar. Do you know exactly why it’s useful? Not sure how ‘Contains’ helps with synonyms. (That said, in the past we’ve talked about tagging components, in backend, with synonyms that would also be filterable…would be great to see that worked into the site). I like the “synonym” filter – both in search and you can also have an optional section on component doc along the lines of “Also called…” For “contains” – I feel like this is trying to do too much work until we have a better distinction between types of components. We should call out “this component is a compound of multiple components”. Do we need that distinction (although I wouldn’t use Atomic Design System terminology, does it make sense to actively call out “Atom”, “Molecule”, “Organism” component categories?)
3. With ‘Similar to’, do we think it’s useful in its current format? Why is it ‘similar’? Why should I know about it? Again, speaking to consumers the only reason it is useful is to quickly find another similar component quickly, without having to search or scroll through a list in the left hand navigation, it is only useful if looking for a specific control that can be used instead of… One thing that came out of my consumer research was that patterns and context examples would be far more useful then ‘Similar to’ as it would show how the component has been used in context and see examples of ‘HOW do I use it?’ and ‘WHEN should I use it?’. Totally agree, and this is what I was getting at. Is there a way we can better present ‘Similar to’, so it doesn’t just show a component but also explains why? I think we should definitely be exploring ‘pattern’ pages (eventually) that show collections and use cases (messaging, selection, containers) and link to those components. Maybe we could also store this text globally and pull section of it into different component pages when relevant? One that we can consider baking into the component pages once we have an up and running pattern library.. or showcase some in context examples on the component pages themselves.. i.e. the Navigation patter we currently have is very useful for our consumers as they can see how Tabs are used and where they can be positioned in an application context. “Similar” could be misleading in implying “you can use this component for the same function”. Carbon uses “Related”, which might be a more relevant term, e.g. shows components that are commonly used together (though they also don’t call out any context on why something is related – and I think we could do better). I agree that as we move towards defining patterns documentation more clearly, this will be a more contextual and helpful way of pulling together different components (and we can do some interesting dynamic filtering or component docs potentially at that point)
4. Did you consider a ‘Tokens’ tab instead? Is that information not also useful to developers, as well as designers? Not yet, I think it would be useful though 😊 when speaking with consumers, it would prove more handy for developers, however designers mentioned they want to see what they would need to change in the token to customize it. I think this makes sense. It can be “Tokens” or “Styling” – but fundamentally “here are the parts of the component and here are the knobs and levers (i.e. tokens) that you adjust for each of its elements.
5. To Robin’s previous point, do we need an accessibility section? In its current form it only really shows keyboard interactions… is it intuitive to find these under code/api? Where we do have specific ada rationale, can we put those points in context instead? (ie., ‘here we made this decision because of this ada consideration’) I like the suggestion around calling out ADA rationale. When speaking with designer consumers they mentioned they would assume the component is already ADA compliant and not necessarily need to reference the rationale or what makes it accessible - unless they need it to provide to a stakeholder. This came out of previous surveys, i.e., a desire to see rationale if certain decisions have been made. Good example is the focus order in the Forms pattern. Personally I think another little call out in line would be all that’s necessary. Another example would be the form field for form controls, and requiring it to be ADA compliant. Less about confirming it’s compliant, but explaining how the compliance impacts implementation decisions. However, having a keyboard shortcuts table or links out to an ADA spec were noted as desirable for our designer & dev consumers. In a broader sense, if we have a principle of having our website explain “why” as well as “how”, this makes sense (and doesn’t have to be limited to a11y explanation. For components, we can’t/shouldn’t be guaranteeing something like “ADA compliance” at all (which we can explain in a more universal section) – but we should be calling out any particular accessibility considerations for a particular component, and (probably separately from the prose usage guidance) listing the checklist of a11y specs that the component has been tested against (and passed!). Language-wise, I would like to add some context whenever we talk ADA compliance, and highlight wider a11y too (as ADA is a US specific law, and for digital presentation is simply WCAG 2.1 compliance – so we could talk about “In order to help teams achieve ADA compliance, and other accessibility requirements, all our components are tested against WCAG 2.1 specifications”.
6. I like the Usage information. Suggest mocking up something hifi sooner rather than later. I wonder if tabs will be visible above the fold, once realistic usage info is in place.
7. Live examples… what’s the difference between show code toggle and show full source code button? The key differences are that the show full code includes the import and export code snippets that we currently don’t show in our current component docs. You can try it out here in material ui. James and I were discussing that it might be a useful feature to have, it also shortens the code block down by default when not showing the full source code.
8. Design guidance. Do we know what designers want to achieve from this tab? Also… if we include any links we need to remember we have internal and external sources. Main info designers want to achieve are in context examples, know what the rationale is between when to use it and how to use it, i.e., when should I use a banner with a high affordance in my app vs a low affordance banner… link of to examples of usage and show patterns of how it has been used before. Designers also want to know where to place components in application contexts (placement) and best practises.. without having to read too much text…less text heavy vs interactable.. see more visual examples. They don’t care about API docs etc so splitting content out is a better idea. Would love to get to the bottom of what’s useful in that ‘design’ tab then? Atm you have anatomy and spacing (although that might just be placeholder content?), and usage information is global. Looking across sites I often wonder if anatomy/spacing/padding/etc is actually useful (it’s also already in specs-and some of those things are foundational, rather than component driven). Love the idea of curated examples (maybe these could be shared across curated best in class, and pulled into different pages relative to tags?). Is ‘Design’ an appropriate tab for that, or something else? Can / should we then split “design guidance” from “usage guidance”? Or does “design” at that point get captured in tab sections like “Styling / Tokens”, and instead we simply make “usage guidance” lean more design heavy.

Often times a lot of websites nowadays (especially websites for content consumption–news, tv services, music streaming) allow you to tailor your experience. Is this something we could take advantage of? Could we allow users to decide what information they want to see by default and cache their preferences? It’s perhaps not v1 😊 but it might help to determine how content could be chunked to be made visible or not. Love this idea and think this could solve for the fact that a lot of our consumers want to surface different info, so having a panel that floats could maximize/minimize at the bottom of the screen to change preferences or a settings section on the site where consumers can toggle certain content on or off might be a nice feature? 😊 I’d see this as an extension of mode/theme controls. They’re all tailoring content to meet a users needs. What do you think? Contextual engagement with the platform is a great long term goal, so that different users – whether self defined or even defined by their team/role – see a slightly different content experience. If we can provide scope for JPM users to have a logged in option with state management, then there are interesting options – but I think it’s a decent way down the line.

[shinytoyrobots]

From @shinytoyrobots

Oh, adding to that…

Based on the doc template outlined in Confluence…

I feel like “Usage guidance” might be not so much a small section under component basics, so much as the container for nearly all the topics that you currently have under Component Basics, Design Guidance, and Other.

So your tabs then become “Usage”, “Styling/Properties”, “Code/Dev Guidance” (or along those lines). And usage guidance is the biggest of those sections. Something along these lines;

Usage Guidance

• Title
• Description
• Compound or simple component (i.e. are other components dependencies?)
• When to use/not use this component
• Variants
• Behavior
• Content
• Accessibility
• Responsive implementation
• Best practices / component reference material (external)
• Related components and patterns

Styling/Properties

• Anatomy
• Spacing
• Characteristics
• Additional design materials

Code/Developer

• Import
• Props
• Classes
• Specs and tests

[shinytoyrobots]

From @bhoppers2008

I like that, although I will keep advocating for a simple, ‘contentless’ view of examples (regardless of how we go about achieving it). I don’t love what Pyjamas does, but I do like that it’s very easy to see what a component is capable of.

[shinytoyrobots]

From @shey-v

I was also keen on the contentless view of examples, however from speaking to consumers, it seems pointless without guidance on how and when to use them. I feel this is useful in a playground environment (if we go with linking out to a storybook/StackBlitz so consumers can edit the live code there). On that – have we made a decision on whether we will be doing this, or is the idea to keep everything on site only?

I’m keen on showing / linking out to patterns and examples in the context of an app, even at a very basic level – which shows placement, best practises and when to use which variant of the component.

[shinytoyrobots]

From @joshwooding

I would heavily recommend using StackBlitz to link out to examples. I would actually advocate for this rather than having editable live examples on the site (although this could be achieved using embedded StackBlitz examples)

Maybe there could be a site wide setting to toggle a “contentless” view? Which would allow for both views to be possible.

[shinytoyrobots]

From @james-nash

Lots of good stuff to talk about on today’s (and future) component page calls.

I think as we work on this stuff, it’s helpful to differentiate between macro and low-level perspectives. By “macro”, I mean things like “What are the sections we have on a component page. How are they ordered and presented? Which sections are mandatory, optional or repeating?”. I’d argue that the finer details of what functionality we provide for each component preview is lower-level. In all likelihood, that would become a UI component we design and develop and then drop into our component pages wherever we need a live example. Functionality like mode/theme/density switches, showing/hiding code, resizable preview area, offering links to ‘open in StackBlitz’, etc. etc. is all component-level stuff we can design and implement independently from the macro-level layout. In fact, if we had such a component preview component, I could easily imagine us using it elsewhere on the site too – e.g articles that explain how to do something with components, getting started guides, etc. etc.

While it’s useful to think about and make a note of our component preview features, I believe our focus right now should be more on the macro level. What we have so far is really good and I don’t think we’re too far off getting it nailed down, but going down rabbit holes about where to put the density switch are perhaps a distraction at this point 😊

I’d love it if we can work towards finalizing the documentation template that’s been started here in Confluence.

In particular, I think it would helpful to start thinking about what format each nugget of information needs to be authored in? Options could include:

• Structured data (e.g. key-values in frontmatter / JSON / TS files) o Do we need to define a schema for this? • Markdown content o Is everything in one big MD(X) file, or do some sections need to be split into separate files? • Example source code o Do/can we use Storybook’s format or does it need to be something else? o How/where is the associated description text and metadata stored? • Images o Do any parts need to be provided as image files? E.g. screenshots, component anatomies, etc. o If so, do things like dimensions and/or aspect ratios need to be set? o Can we make a (Figma) template to speed up producing them? o How/where is associated alt text, caption text, etc. provided? • Embedded content o Do we need/want to embed things from external sources – e.g. Figma previews? o What are the page speed, UX and a11y implications of doing that?

I appreciate some of that stuff will be informed by whatever page layout and design we come up with and also our tech migration to Mosaic+Next.js, so we can’t answer everything right now. However, the sooner we can get a reasonably clear checklist of everything a component team would need to provide, the sooner those teams can begin authoring content like that.

Longer term (a subset of) this content checklist could also serve as what we ask spoke design systems to provide for our community index.

[shinytoyrobots]

From @joshwooding

I would agree that it’s better to focus on goals rather than details that get be easily changed in the future. Although I would consider the format of the information an implementation detail that can come later too. I think rather than producing a checklist of everything that needs to be done a high-level overview plus tiny scoped pieces of prioritised work that we could start looking into tomorrow would be better.

Finalising the documentation template seems like a great first step!

[shinytoyrobots]

I agree the high level goals, and that informing the overall structure, makes sense.

I’d like to suggest we try and distil the aim of a component documentation page into a sentence or two, based on the problem statements identified in the research @shey-v summarized today. That can then act as a north star to refer to when we get into more minutae.

I discussed with Shey the potential benefit of looking at a high-data-fidelity (but still low visual fidelity) approach for the existing structure - i.e. populating with a specific component doc rather than lorem ipsum - and seeing how that looks. I'm happy for @shey-v / @sion-docs to finalize a v1.0 of the template on that basis, for review at that point.

[JohannaJoergensen]

8 Feb - work in progress

[sion-docs]

I agree the high level goals, and that informing the overall structure, makes sense.

I’d like to suggest we try and distil the aim of a component documentation page into a sentence or two, based on the problem statements identified in the research @shey-v summarized today. That can then act as a north star to refer to when we get into more minutae.

I have created a Lucid board at https://lucid.app/lucidspark/a00552b6-b5d5-49cd-8903-bebd23314311/edit?viewport_loc=-9%2C-8%2C1558%2C885%2C0_0&invitationId=inv_e77d3cf4-f476-4276-8d47-31b89a2ad531 where we can add our suggestions for the above sentence.