Clayui.com documentation, how enhance it? 🤔

[diegonvs]

I've fill this issue to share some thoughts and start a discussion about how we can improve our website docs.

• We will work on integration of clay-paver on clayui.com. So, we are thinking of putting it on another page so we do not conflict with other css files, do you guys have any suggestions?

• Our LATAM design intern @gabbebarbosa, had made a document during his internship rotation describing some enhancements on clay docs website.

Check it out here:

Note that she had put a table with some API description on each component.

Also, she said that would be great for us have a section to fill a issue if the provide documentation is wrong. I've noticed that we have a icon that redirect to Github issues but isn't too much.

• Last weekend i attended to Braziljs conf and i talked too much with a lot of Front End developers, including a girl that works on a company that has a design pattern system and component library similar our. She said that a lot of problems using a design system on his company was solved by:
  • A good documentation, including API full description like: http://circuit.sumup.com/#/components/blockquote. I think Gabbe's layout work will solve it.
  • A place to workbench API like Storybook, @matuzalemsteles had built a utility to use this feature on current documentation with /try page. Like: http://circuit.sumup.com/storybook/
  • A section to include Best Practices for each component.

/cc @pat270 @matuzalemsteles @jbalsas @marcoscv-work

[jbalsas]

Hey @diegonvs, the circuit links are not working... 🤔

@marcoscv-work went through the current component list with the Lexicon team and this is the proposal they came up with

Page Structure clayui.com Proposal

• Get started
• Introduction
• What is Clay
• Importing the JS Component
• Web Components Using JS Components with Metal.js
• Layout
• Lexicon Core Components (1 : 1 from Lexicon-site Core Components section:)
• Alerts
• Badges
• Buttons
• Cards
• Charts
• Charts
• Colors
• Interaction
• Bar chart
• Doughnut chart
• Heatmap chart
• Line chart
• Pie chart
• Stacked bar chart
• Confirmation Message
• Dataset Display
• Dropdown Menu
• Empty States
• Forms
• Forms
• Forms Hierarchy
• Forms Navigation
• Forms Rules
• Forms Validation
• Checkbox, Radio, Toggle
• Multi Step Form
• Multi Step Form Simplified
• Selectors
• Slider
• Text Input
• Text Input Group
• Text Input Localizable
• Text Input Variations
• Icons
• Labels
• Link
• List
• Loading Indicator
• Modals
• Navigation
• Breadcrumb
• Navbar
• Vertical Navigation
• Pagination
• Popovers and Tooltips
• Progress Bar
• Sidebar
• Sidebar
• Info Panel
• Stickers
• Table
• Table
• Inline Edit Table
• Tabs
• Toolbars
• Toolbar
• Management Toolbar
• CSS Framework (Everything we need to document apart of Lexicon components, for example:)
• Font
• Our class helpers
• Full component variations
• Page examples
• etc..
• News

A couple of things we need to do:

• Incorporate the contents from http://pat270.github.io/lexicon/ into these sections so we can remove it. Only things that serve as developer reference should be published to the site and it all should live in the same site
• @pat270 has been using http://pat270.github.io/lexicon/ for local development and smoke testing. We should set this up somehow so it can be used locally within the clay-css package, but without the risk of producing a live site. @pat270, can you share with @diegonvs and @matuzalemsteles what you need so they can help you out here?

[matuzalemsteles]

I think it's worth exposing an API table in each component on the pages, people are starting to use it and they are missing something to be able to walk. They are lost in how to use...

I also like the idea of exposing a good practice session, but maybe not for all the components but some other session.

[jbalsas]

Hey @matuzalemsteles, I really like the idea of having the API table exposed. We developed an electric task to automatically generate the API page. You can see it in action in AlloyEditor > API.

Could you guys figure out how this would work for our Gatsby site? Ideally, it should be autogenerated from our jsdoc, so we don't need to write it twice... what do you think?

[matuzalemsteles]

@jbalsas yes I've been thinking of something similar, but not having a page just for that, but on every page of the component but automatically without having to change something at hand.

[jbalsas]

Sounds good to me try it out separated by components. Let's see how to make that happen! :)

[jbalsas]

Hey @matuzalemsteles, @diegonvs, now that we've pushed through with the API docs for the components, and while we discuss how to Improve the clayui.com deploy process, could you guys focus on the following, please?

• Incorporate the contents from http://pat270.github.io/lexicon/ into these sections so we can remove it. Only things that serve as developer reference should be published to the site and it all should live in the same site
• @pat270 has been using http://pat270.github.io/lexicon/ for local development and smoke testing. We should set this up somehow so it can be used locally within the clay-css package, but without the risk of producing a live site. @pat270, can you share with @diegonvs and @matuzalemsteles what you need so they can help you out here?

Just today we had again an issue where someone was looking how to create a simple loading indicator and had to end up looking at http://pat270.github.io/lexicon/content/loaders/ rather than https://clayui.com

This is our biggest barrier on usage and consistency. We need to address this

Please, could you take a look at the structure proposal and go through the current docs to merge in what's not in the right place and see what should be brought over from @pat270's site?

After we're done with this, we should be able to redirect the other site to https://clayui.com

[matuzalemsteles]

Only things that serve as developer reference should be published to the site and it all should live in the same site

hey @jbalsas this part was not very clear to me. Could you clarify a little more 😅? what contents should move?

@pat270 has been using http://pat270.github.io/lexicon/ for local development and smoke testing. We should set this up somehow so it can be used locally within the clay-css package, but without the risk of producing a live site.

hey @pat270, @jbalsas what do you have in mind about this? I've been thinking about creating a link from the clay-css package to clayui.com in a task, this can help @pat270 to be able to work from the site without sending the changes to production. Maybe we can also try to create certain pages appear only in development environment, I do not know if this would really solve the problem, I would like to hear your ideas on this.