Documentation: FlexCSS could be improved

[geoidesic]

The FlexCSS documentation here could be improved.

Firstly the order in which the information is presented is confusing. It starts out with a whole TLDR and when one scrolls down to the Getting Started bit the eye is immediately drawn to the diagram, which uses terminology "Container" and "Items". Most people will miss the bit above which in parenthesis shows that these are also called ("Parent") and ("Children"). The parenthesis de-emphasises the importance of those alternate terms, setting up the expectation that the other terms will be used. But then the documentation goes on to use the alternate terminology! Confusing.

I would suggest either adding Parent and Children to the diagram also or changing the headers "Parent Classes" and "Children Classes" to either also include parenthesis with the same emphasis as in the paragraph that introduces them, or just to use the main terms, whichever you deem those to be. The important thing is that you don't keep switching emphasis.

I would move the following example up to the top of the page, just below the first paragraph which ends with "... options at hand."

I would also alter it to contain comments illustrating the parent child classes, e.g.:

<div class="row">  <!-- use 'row' class to define a container / parent -->
  <div>First column</div>  <!-- children will default to 'col'  -->
  <div>Second column</div>
  <div>Third column</div>
</div>

This gives people what they want immediately.. an example with comments that show immediately what things mean.

The next problem is that the Parent Classes section seems to be confused in it's intent. It starts with a sub-header that says "Setting Direction". To anyone new to flex in Quasar they will immediately think.. "oh, don't need that yet.. still trying to figure out how just to set up the basics".

Confusingly the intro text below the "Setting Direction" header has nothing to do with setting direction and says "one of the following css classes is mandatory for the parent in order for the children ones to have any effect"... so two problems with this. Firstly, it's setting up an expectation about the content then providing unrelated content. Secondly it says "one of the following classes" but then is immediately followed by a diagram showing directions again, which seems related to the heading but not to the intro paragraph (it's also not clear how the diagram relates to anything really.. it's just there). After the diagram come a list of classes, some of which seem to have to do with setting direction and some of which do not. So it's confusing to digest this. It's then followed by an example which has nothing to do with setting direction.

Now after this section it may be worth saying something like "Tip for newbies: start with a simple parent, just with class="row", then skip ahead to the "Children" section to see how to define your columns".

It would also be worth re-iterating in each sub-section that the classes in that section pertain to "parent" or "children". I know the hierarchical structure of the doc indicates this but if you're skipping around the document it's easy to miss because it's a long document and like an Anish Kapoor sculpture you can't see all of it at once, so it can be hard to figure out what relates to what.

I think it's also worth stating somewhere in the intro that all that's required is a parent class definition and children inside the parent as per the first example, nothing else. This fact isn't immediately obvious because when you paste the example in, existing CSS may make it less than obvious what's going on and it might not be the exact effect one was looking for. So these questions come into one's mind...

• does it matter what the parent of the parent is? Must it be q-page or flex or something
• must I define height and width on the parent?

The "Responsive Design" section is a bit confusing. From the Discord channel I discovered that one can use those tokens in a different context defined here: https://quasar-framework.org/components/visibility.html#Window-Width-Related

One of the confusing things to get used to with flex is how to hide show items at different sizes and it's not described in the FlexCSS docs at all, it's hidden on the link above. So I would suggest adding something like a note: "Not to be confused with visibility classes which allow you to hide and show elements at given media-views breakpoints" along with a link to the visibility components link.

Or maybe put them on the same page. They really are related for anyone trying to get to grips with flex and breakpoints.

Another really confusing thing is that if one looks at the source of the FlexCSS examples you see class="q-mb-lg" but this isn't explained anywhere in the docs. I spoke to Robin about it and he spewed a whole bunch of Stylus at me which he said couldn't be included in the framework because it generates too much css. The reason this is confusing is because often when columns wrap they don't have any vertical margin, which looks messy. If one adds margin to the children, then they can end up misaligned at certain breakpoints. If one uses the gutter-xs type classes you get gutter left and right also, which is not necessarily what you want. Robin's classes sound like they might help with that, so I strapped them in only to find that they don't and that the only way to do what I want is to set a negative margin on the parent and then a margin on all children. That way you don't see the margin when they are inline, only when they wrap. It would be really useful to document this technique and describe the problem and solution.

It took me weeks to get to grips with all the above and I see a lot of people just don't bother with Flex and end up trying to recreate it – I think these improvements to the docs would go some way towards improving that situation.

Also have a look at this documentation here for inspiration, which I found a lot easier to read and to understand when first learning flex: http://flexboxgrid.com/

[rstoenescu]

Top notch analysis. I agree with all of it.
One note though: the "q-mb-lg" examples comes from Spacing classes -- something other than the flex css: https://quasar-framework.org/components/spacing.html

Would you like to take the lead on refactoring the flex doc page, based on your thoughts?

[rstoenescu]

@geoidesic what do you think?

[geoidesic]

@rstoenescu sure I'll do that. Bear with me though as it will have to be in spare time, which is in short supply at the moment until I manage to get QUploader working on my project.

[nothingismagick]

@geoidesic - Are you planning on updating the docs in this regard? We spoke about it yesterday...