RFC: Unified tech docs

[pearofducks]

Rendered: https://github.com/fabric-ds/issues/blob/tech-site/rfcs/0001-tech-site.md

[digitalsadhu]

So the idea would be that we use this abstracted version of props and translate that into each framework implementation?

[pearofducks]

IMO is OK if a framework deviates so it feels more native, but would be great to share names as much as possible so we can share descriptions and have a common API

Descriptions could be a separate object to support this, and we could change the props shape to support something like this:

const buttonDescriptions = {
  href: 'Will make the button an anchor tag and use this for href',
  disabled: 'Don't do this'
}

const vue = {
  button: {
     props: decoratePropsWithDescriptions({
       href: ['string', undefined]
     }, buttonDescriptions)
  }
}

[digitalsadhu]

Agree with motivators 👍

[digitalsadhu]

So do I understand correctly... we would keep the design and CSS docs as is and then merge Vue/React and Elements into a single entity?

[pearofducks]

IMO the CSS docs are 90% playground, so we could move the few sections that are actual docs/guides into this site

[digitalsadhu]

IMO the CSS docs are 90% playground, so we could move the few sections that are actual docs/guides into this site

ok, so keep design as is, merge all others into 1 "technical docs" site?

[pearofducks]

Yup!

[benja]

Great writeup!

I was under the impression that we wanted to go for a single sidebar entry and not splitting up between the frameworks, and showing different implementation levels like so:

Although that doesn't give away immediately what frameworks a component is supported in, so we could combine that approach with badges on top of the page for which JS-libs supports this component. E.g. something like this:

What are your thoughts on this approach?

[pearofducks]

I don't think the suggestion/example from Vitepress is notably worse than that, just different.

If we can get that UI "for free" from some other framework (and we don't lose any other features we want/need) and we want to go with that, I'm fine with that.

(Because of how Vitepress manages the sidebar, I don't think we could do both Vitepress, and get its free intersection-observers, and do this tabbed approach)

[Skadefryd]

Why exactly do we want to meld together just the tech sites and not all of them including design site into 1? Tech reasons?

[pearofducks]

@digitalsadhu or @benja would need to speak to that (whether that's a practical option). I would not be involved in implementing that change and am not familiar enough with Next to say.

The framework I'm working with right now at least is pretty lightweight and gives us 99% of what we want for these docs (at least vs the requirements I've put above), I don't know if the design doc does the same.

[digitalsadhu]

Thoughts on merging everything into 1 site:

Advantages:

• Easier to maintain a single site
• Better user experience (eg. unified single page for everything for a single component) important!

Disadvantages

• more work?
• keeping things in sync
• automating generating docs from (for example) components is harder

Advantage 2 is super important, can we mitigate the disadvantages? Eg. Agree on a way to write docs/stuff in the individual repos that we then fetch automatically from the docs site.

[pearofducks]

I'm on the fence on whether this is a better UX for developers, but I don't feel strongly about it so I'm happy to defer to y'all.

I personally haven't referred to design docs/specs in the past few years while developing, they're usually different contexts for me.

Worth also noting most design systems do not have unified docs. Not saying that means things one way or another, but the big boys aren't doing it and they definitely have more resources than we do.

---

As long as you could fetch markdown as well as structured data like props I think it would be doable. There will definitely be concepts in each framework that require blocks of markdown that are different from the other framework(s) to detail.

Also things like how to setup/install components is different between Vue/React, so it'd be important to have some flexibility.

[digitalsadhu]

Starting to think we would do well to take a step back, schedule a planning meeting and figure this out.
Be good to work out what we all think the best user ex would look like and then work out what's actually practical from there maybe.

[pearofducks]

@digitalsadhu - sounds good to me! Also sounds like you just volunteered to set that meeting up! ;)

[digitalsadhu]

@digitalsadhu - sounds good to me! Also sounds like you just volunteered to set that meeting up! ;)

I guess I did at that

[digitalsadhu]

Documentation Planning Meeting 25/11/2021 14:00

Notes:

In summary, the group discussed optimal design and layout of a documentation site from a pretty high level. Highly specific discussion regarding technology stack etc. was not touched on in great detail.

Goals

@digitalsadhu suggested our main goals to be:

• Improved user experience
• Reduced maintenance

Design Documentation in Figma

@benja made the suggestion that it might be easier to document design inside of Figma instead of in the documentation site itself. This idea seems to have merits but there is also a fairly strong sentiment that we should keep all documentation in one place.

Previous Design Work

@adidick showed some earlier designs where each component gets its own page with some up front initial information and a set of tabs underneath. 1 tab for design and 1 tab each for React, Vue, CSS and Elements. This seemed to be fairly well received as an approach and comes with the advantage that there is a single page for each component rather than a page for each component in each section.

Tabbed Documentation

Trygve mentioned that in the Podium docs we use tabbed code examples for the various framework options and which this makes for a good user experience it can quickly become unwieldy to maintain. This could be perhaps avoided by pulling in readme docs from the repos themselves rather than try to maintain them in 1 documentation site.

Accessibility

@martin-storsletten raised 2 concerns:

1. Too much information could cause developers to ignore documentation
2. Duplicating accessibility documentation across the various frameworks is non optimal

Decisions

We decided @adidick would try to prototype something for further discussion. Also a good idea to try to work out a common structure for technical docs

TODOs:

• Mockup a unified documentation site structure for further discussion. (@adidick)
• Propose a common structure for laying out technical documentation for the various frameworks (@digitalsadhu and/or @pearofducks and/or @benja)

[digitalsadhu]

We should probably keep things moving and move pretty quick on this so let's set a date for the 2 TODOs in the meeting writeup.
Creating a proposal for a common structure for technical docs could be done pretty quickly I suspect but we do have Kick Awards looming... Can we get it done by Tuesday?
How much time do you need for the design stuff @adidick ?

[digitalsadhu]

Trying to think through what we want in the technical docs for the components...
Hows this for a starting point?

• Setup
  • import from ... etc
• Basic Example
  • Most basic usage of the component
• Accessibility?
  • Do we need individual UU guidelines in the technical docs for each component?
• Properties/arguments
  • Table of properties
• Additional examples
  • More examples for the different variants of property options

[digitalsadhu]

How do we feel about adding a "see implementation" link to each component page? Ref: #16 Is this something to add to the mockup @adidick ?

[benja]

Great starting point. I think a11y definitely should be a part of the component implementation / props structure. Some components require a bit more attention to a11y, such as the Card, if you wish to make it a clickable anchor card. So having the option to go quite in-depth is good.

[digitalsadhu]

Trying to think through what we want in the technical docs for the components... Hows this for a starting point?

• Setup

  • import from ... etc

• Basic Example

  • Most basic usage of the component

• Accessibility?

  • Do we need individual UU guidelines in the technical docs for each component?

• Properties/arguments

  • Table of properties

• Additional examples

  • More examples for the different variants of property options

Thoughts from @pearofducks via Slack:

• Additional to props is slots, events, and sometimes an arbitrary table like the button-combination one
• Would be nice to have a working example up with the title, even if the most basic variant
• Disagree with having "more examples/tokens", I think we should maybe link to the playground where more examples can be found. Rationale: IMO this is going to lead to users asking "can we add that to the examples" every time they don't read the docs and need to work something out on their own