Skip to content

RFC: Unified tech docs #18

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
pearofducks wants to merge 1 commit into
base: master
Choose a base branch
from
Open

RFC: Unified tech docs #18

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 55 additions & 0 deletions rfcs/0001-tech-site.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
# Summary

A single site that has documentation for developers spanning the frameworks Fabric supports.

# Motivation

Several key motivators:
- One page to refer to from design docs or userland
- A single experience for the user, and for the Fabric team to maintain
- Leaves the implementations to only worry about dev-playground sites instead of one/both
- React currently has both a docsite and storybook
- Vue has a combined approach
Copy link
Collaborator

@digitalsadhu digitalsadhu Nov 22, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agree with motivators 👍


# Details

Loose example here: https://fabric-tech-poc.surge.sh/button/ - both Button and Pill have early pages

- Supported frameworks for a component should be clearly visible (via tabs, sidebar, whatever) - clearly indicating to the user that if the framework isn't there, it isn't supported (yet)
- Should be possible to view a minimal working example of the component
- Props should be able to be defined using JS so we can mixin/reuse descriptions [0]
- We should use a framework to handle markdown/prism/sidebar stuff, we should not be doing that setup/maintenance ourselves
- Ideally also supporting components/logic

[0] Example of data for props

```js
Pill: {
required: [],
props: [
['label', 'string', undefined, `The pill's label, complicated stuff`],
['canClose', 'boolean', false, 'If the pill should be removeable'],
['suggestion', 'boolean', false, `If the pill should have suggestion-styling`],
]
},
Button: {
required: [],
props: [
['label', 'string', undefined, 'Interchangable with the default slot for labelling'],
['href', 'string', undefined, 'When set, an anchor tag will be used instead of a button'],
['type', 'string', 'button', `Controls the button's type, unused when href is present`],
]
},
ButtonVariants: {
titles: ['main', 'combinations'],
rows: [
['primary', 'negative, small'],
['secondary', 'quiet, small'],
['negative', 'quiet, small'],
['link', 'small'],
['utility', 'small'],
['pill', undefined],
['loading', undefined],
]
},
Copy link
Collaborator

@digitalsadhu digitalsadhu Nov 22, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Collaborator Author

@pearofducks pearofducks Nov 22, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)
  }
}

```