Skip to content
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.

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

Documentation v2 #20

Open
wants to merge 4 commits into
base: master
from

Conversation

@ahuth
Copy link
Collaborator

commented Aug 1, 2019

  • Separate readme into sections
  • Slight tweaks
  • Document variation provider extras will hold off
  • More documentation about consumers will hold off
  • Document how to run in a project will hold off
  • Maybe add quickstart documentation will hold off
@ahuth

This comment has been minimized.

Copy link
Collaborator Author

commented Aug 1, 2019

- [Consumers](#consumers)
- [Contribution Guidelines](#contribution-guidelines)

## Variations

This comment has been minimized.

Copy link
@indiesquidge

indiesquidge Aug 1, 2019

Member

Does this work by default with the table of contents, or does it need to have an explicit anchor link?

[Variations](#variations)

## <a name="variations"></a>Variations

This comment has been minimized.

Copy link
@ahuth

ahuth Aug 1, 2019

Author Collaborator

It totally works


## Variations

Variations are defined in files we call variation providers. These are standard Javascript modules that return an object with specific fields. For example:

This comment has been minimized.

Copy link
@indiesquidge

indiesquidge Aug 1, 2019

Member

Would it make sense to elaborate on these "specific fields" that a variation provider's return object needs to have?

This comment has been minimized.

Copy link
@ahuth

ahuth Aug 1, 2019

Author Collaborator

Yeah

This comment has been minimized.

Copy link
@ljharb

ljharb Aug 1, 2019

Collaborator
  • JavaScript
  • they're not actually standard JS modules, they're node modules, which atm are just commonJS
Suggested change
Variations are defined in files we call variation providers. These are standard Javascript modules that return an object with specific fields. For example:
Variations are defined in files we call variation providers. A "variation provider" is a node module that exports a function, that returns a "descriptor object" with specific fields. For example:
README.md Outdated
@@ -34,13 +43,17 @@ export default function ButtonVariationProvider({ action }) {
}
```

We also have "consumers" that use the variation provider to perform tasks. Example consumers are:
Each variation provider will be passed an extras object. It's properties come from the project's configuration, and can be used to get mock data needed to render the variations.

This comment has been minimized.

Copy link
@indiesquidge

indiesquidge Aug 1, 2019

Member

Being someone still unfamiliar with the extras object, this statement is a little nebulous to me. Where/what is the project's configuration? What type of mock data are we talking about?

I'm thinking we either don't get into the extras object just yet (it is a more advanced feature after all—variations work fine without any extras), or we go into more detail about why extras exist, what problem they solve, and how to set them up. (I'm personally more in favor of not mentioning them up front here in the intro section of the README.)

This comment has been minimized.

Copy link
@ahuth

ahuth Aug 1, 2019

Author Collaborator

Yeah, it's definitely more advanced. And I haven't covered how to actually integrate this into a project yet. So you're probably right

Remove all mention of extras from the basic docs
Extras are a more advanced feature, which I'll cover once we get to integrating into a project.
@ahuth

This comment has been minimized.

Copy link
Collaborator Author

commented Aug 1, 2019

@indiesquidge , @sharmilajesupaul , and @ljharb , what do you think about these minor documentation tweaks?

@@ -2,19 +2,28 @@

⚠️ **Warning: this project is still very alpha**

This project is:
React component variations are:

This comment has been minimized.

Copy link
@ljharb

ljharb Aug 1, 2019

Collaborator

Technically the variations are just part of the descriptor object that variation providers return.


A variation looks like:
## Table of contents

This comment has been minimized.

Copy link
@ljharb

ljharb Aug 1, 2019

Collaborator

it might be nice to use a tool like doctoc (example) plus a CI check, to ensure that this can easily stay up to date.


## Variations

Variations are defined in files we call variation providers. These are standard Javascript modules that return an object with specific fields. For example:

This comment has been minimized.

Copy link
@ljharb

ljharb Aug 1, 2019

Collaborator
  • JavaScript
  • they're not actually standard JS modules, they're node modules, which atm are just commonJS
Suggested change
Variations are defined in files we call variation providers. These are standard Javascript modules that return an object with specific fields. For example:
Variations are defined in files we call variation providers. A "variation provider" is a node module that exports a function, that returns a "descriptor object" with specific fields. For example:

```jsx
// ButtonVariationProvider.jsx
import React from 'react';
import Button from '../components/Button';
export default function ButtonVariationProvider({ action }) {
export default function ButtonVariationProvider() {

This comment has been minimized.

Copy link
@ljharb

ljharb Aug 1, 2019

Collaborator

it seems important to have the example include the "extras" functionality, since it's so critical for storybook.

This comment has been minimized.

Copy link
@indiesquidge

indiesquidge Aug 2, 2019

Member

But isn't that just one consumer of variations? It still feels like an advanced feature to me. If we want to include it in the "here's what you need to know right out of the gate" part of the readme here, I think we'd need to make sure we provide the "why" and "how" on top of the "what" as it relates to extras functionality.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
3 participants
You can’t perform that action at this time.