Closed diegonvs closed 5 years ago
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
A couple of things we need to do:
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?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.
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?
@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.
Sounds good to me try it out separated by components. Let's see how to make that happen! :)
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?
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
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.
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
...
What do you think?
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?
hey @jbalsas, Thanks for the clarifications and I agree with you! Sorry for the delay! But I'm already working on it....
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?
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.
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 :)
I think that we need a way to show users our supported browsers. I didn't find anything unless give a table with supported browsers like google/material-design-lite. Do you have any suggestion guys?
hey guys,
I do not know if we have to follow the "Lexicon Core Components" session with the Lexicon session, we are leaving aside some extension components of Clay Charts, we have to document and say that they exist. Any suggestions on this?
cc @jbalsas
Hey @matuzalemsteles, can you be a bit more specific? I'm not sure I understand what you're referring to, here :/
Ah sorry, I was not so clear! 😅
Since we will follow the proposal to organize the documents of the Components
session, we will have to remove some docs. What we will do with the Radar, Geomap and Scatter documentation for example. Can we create a Charts extension session? within the Charts
session.
Hey @matuzalemsteles, makes sense now!
I think in this case this is more of something missing in Lexicon. They will be working to add it to their documentation, so we can keep it as it is for now.
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.
/cc @pat270 @matuzalemsteles @jbalsas @marcoscv-work