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.

[matuzalemsteles]

hey guys, it's just a thought: Since @pat270 can use the site clayui.com for tests and experiments for future versions, we can create Clay Nightly (Just a code name) that will stay in another environment of WeDeploy, the idea is that @pat270 continue developing on clayui.com but we can create a configuration for Gatsby to hide pages marked as Nightly...

• Nightly - Future versions of Clay, an area for experimentation and testing of things that may not be released... This can help other people view and be able to give their opinion.

What do you think?

[jbalsas]

Hey @matuzalemsteles!

We need to separate the concepts.

Documentation needs to be thoroughly thought out. It needs to have a purpose and be presented in a way that can be found, searched, consumed and shared with developers. We need to be making conscious decisions as to what we document, because those are the things we need to maintain and support.

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

This means that we need to think of what's our API, what do we want to expose and get people to use and in which ways?

Development process does not need to be documented. We need to figure out what's the best way to develop and test css. For the moment, @pat270 has a clear workflow that we should maintain, but that development workflow should have no impact on what is documented. In the future, we should try to improve our process to add automated regression testing and different approaches that don't involve manually checking everthing over and over.

Makes sense?

[matuzalemsteles]

hey @jbalsas, Thanks for the clarifications and I agree with you! Sorry for the delay! But I'm already working on it....

Documentation

This we really need to discuss, I think we currently have some documentations that are only there to fill a space but I do not know if they are really helping or disturbing sometimes I feel that people think they have limitations because they do not see what is documented or not see... (Maybe it's my impression).

I do not have an idea how we can organize the CSS documentation. If we will expose the variables (SASS) of the components. Do we want this?

Development

Sure, when I say that separating a Nightly environment for Patrick to "document" would be it is only creating visual test markups without going into production, it could see how CSS will reflect on the documentations markups as well as is done at http://pat270.github.io/lexicon/. I think he will have a richer environment to test while he can document, I do not know if he wants it, but I can send him a proposal to test him and see what you think.

About automated testing, I ended up finding a utility for Jest, maybe this can help test visual things.

• https://github.com/americanexpress/jest-image-snapshot

[jbalsas]

Hey @matuzalemsteles, thanks for the answer and additional feedback! 👍

Documentation

On the CSS side, we need to document things that CSS/HTML developers might need, such as mixins, helpers, special classes...

Documenting variables would be a huge and probably useless effort (we have soooo many of them). I think we could simply have a page with an introduction for that with a link to the Clay Paver page where we can more effectively play around with variables.

The last bit is that we need to have all the markup documented along with the components. If some are not part of Lexicon but we still want to document additional markup, then we could add a special section "others" or "satellites".

Development

Sounds good to me, please, sync with @pat270 and let's work on a proposal for our internal development workflow. Keep in mind that we want others like @marcoscv-work and yourself to also contribute there :)

I'm happy if we can settle on the manual process for now. We can think about automating some things in the future. @john-co should be able to start thinking about it as well :)