Add configuration examples to docs widget table #486
Comments
|
@erquhart I've suffered quite a lot with the lack of a better widget documentation. For this reason I'm excited to make this my first contribution 😄 Eventually Caleb sent me a link to the kitchen sink config.yml, but I'm still unsure about the possibilities of certain widgets... That's why I think that, besides providing examples, we should redesign the table in order to include more room to talk about each widget. Thinking about that, I've quickly sketched 3 different approaches for a new section, all following the principle of progressive disclosure. Basically, we don't want to show every widget at once as the list might grow and as it limits the amount of information we can have for each item - else it'd be too heavy on the eyes, super intimidating - and so we only show them when the user asks - AKA clicks on a field or scrolls down. My first and favorite idea is using a type of word cloud with each input name, as shown in the image below, and then show only the one with active state - which changes as the user clicks each cloud. It's very easy to make this system responsive and it has quite a lot of room for individual information! As a bonus, I've also thought of creating a simple form that generates fields based on user input. The "Options" part of the image above would change based on the "Widget" input value, transforming into "Format", for example, in case the user selected the date widget. Again, following the word cloud visual, each value for the options could be easily created or deleted without polluting the page with a bunch of inputs. Following the same principle but still keeping part of the table aspect of the current model, I thought of using a clickable accordion. Even easier to make it responsive and even more room than the word cloud solution, but a bit less pleasing on the eye, in my humble opinion. Finally, inspired by Hugo's documentation I've also created cards as a proof of concept, but I think it'd take too much scrolling for the user, especially on mobile... These are all the ideas I had so far, but I'm willing to discuss them freely and search for further options 😃 I can also do the actual coding of whichever option we choose, just gotta figure out the project structure and then I can make a PR, my first one (exciting)! PS: I've included the .xd file I've used to create this as a zipped folder below: |
|
This is SO awesome, I love it!! I think an ideal scenario would be to pull the generator concept out into a separate web interface that we link to from the docs, maybe even in a separate section of netlifycms.org. We've also discussed creating a config validator as a web interface, so maybe we'd have a few of these tools over time. For the display of widget info in the docs, these are all really great concepts, and I'm honestly torn. I like the cloud most, but it feels like that spice on the side is a bit constricted, especially for more complicated widget configuration examples. I'd also like space for one or more images to help folks better understand what the widget is. The expandable table might be the best compromise overall, but again, torn. @neutyp @rafaelconde any thoughts from the design pros? |
|
Awesome! Sign me in for the config validator and the whole generator thing when it's due time ;) About the cloud, I totally agree with you, in fact this was one of my main concerns about it... There are pretty much two ways I can see to work around this:
|
|
Yep, this could definitely work! As long as there's room to properly whitespace the code sample for clarity, this seems like a great approach. cc/ @verythorough would love your thoughts on this too. Regarding the generator, I'd be cool with just adding a Tools section to the docs and putting it there for now. Probably need to play with Hugo a bit to get it going, but if you're up for that a PR would be awesome. |
|
Sorry, I've been under the weather and not keeping up with things. I'm really excited about these ideas, and have been thinking about how to implement them. |
|
Unfortunately this week and the start of the next are a bit frantic with school and some client work, but I'll begin with the widget cloud next Wednesday or Thursday - and, of course, paying attention to the whitespace and clarity of the code. When I'm done with that, I'll fiddle with Hugo and see what I can do, but in advance I'll tell you I'm not the best JS developer out there, so the generator code might be a bit messy - which is great for me cuz it'll allow me to learn, but might be tedious for you and the other maintainers to check on it. Anywho, we'll see how it goes, gimme a week and I'll have the widget cloud ready :D |
|
Sounds great, looking forward to it! |
|
I'm looking forward to your work, @hcavalieri! To save you some trouble and get a better reference in place in time for 1.0, I'm going to lay some groundwork and get all of the widget info spelled out in (relatively) plain text. I'll add each widget under an H2 (so they're linkable from the sidebar), with the characteristics you list in your mocks. Once those are in, you can apply fancier functionality when you get the time. |
|
That's awesome, @verythorough ! Jessica, I can help you with that, but I think it'd be beneficial if you took a look at the WIP PR for this section as I've took my liberty to change the way the widgets content is served to the Docs: now each widget will have its own While we don't have all the info for each, I'll finish styling the section and making sure all is good and round for merging, then we need only fit in the |
|
I believe this was closed by the 1.0 release docs, plus #866 |
The current widget documentation doesn't explain how each widget should be configured. One approach would be to add example configurations to the table of widgets in the docs.
The text was updated successfully, but these errors were encountered: