Index of all CSS class names

[jpmckinney]

After contributing a bunch of issues and pull requests in April to improve the docs, I've finally gotten around to trying to implement wet-boew for a Library of Parliament website.

A common first task when adopting a framework is to set up the layout template with all the necessary header and footer code.

It seems the only way that the current documentation supports this is by learning by example (by inspecting source code), by going to "Working examples", then "Base theme", then select a page in your language, then view source. However, all the ID and class attributes are opaque, like "wb-tphp" "wb-slc" and "wb-sl" just to pick the first three. There is no page where I can look up these IDs or class names to find out what styles are applied when they're used, or what JavaScript behavior is attached to them, if any.

So, I can't use wet-boew, because it's currently impossible to work backwards from the examples and figure out how the pieces fit together.

With Bootstrap and other frameworks, the class names are human-readable, and easy to find in their documentation.

For wet-boew, I suggest that there at least be an index of class names that link to relevant documentation.

[LaurentGoderre]

Are you trying to implement an existing theme or create your own?

[jpmckinney]

I will ultimately create my own, but simply being able to use the base theme would be a good start.

[pjackson28]

@jpmckinney We originally had more human-readable class names in WET v3.x but the drawback with that is that it significantly increased total download sizes, in the range of 10% to 20%. The download sizes need to be kept low (200kb to 500kb) to support mobile devices.

As for documenting what each of those classes are used for, I think that is a good idea. It would help people to better understand the sections of the markup and more easily map it the on-screen results. Would you be interested in helping to document that? Would be good to know the type of information that would be helpful.

As for describing in the documentation what styles are actually applied, that could get very complicated and I'm not aware of any framework that is currently doing that (beyond a high level overview). Fortunately many development tools (e.g., Firebug, Chrome developer tools) make this much easier by allowing you to determine what CSS is being applied at any given time.

As for JavaScript, what type of information are you looking for? Were you looking for a high level overview of how the framework operates or were you looking for much more detail? There is a lot that could be documented so how much information do you need to build your theme?

[jpmckinney]

I just mean a narrative description of what the CSS class names mean. I happen to know that wb-tphp stands for "WET BOEW Top of Page / Haut de Page", because it was mentioned in an issue. Having a page that maps the ID and class names to human-readable one-sentence descriptions would be a good start. In the case of wb-tphp for example the sentence might explain what the purpose of wb-tphp and the other classes that commonly appear with it are (i.e. explain that it's for screen readers). Right now, I don't think wb-tphp appears anywhere in the documentation. Undocumented features make adoption harder.

With respect to JS, I can see from the examples that there's a wet-boew.min.js file, but there is no documentation about what that file does. Are all its behaviors opt-in (i.e. it's just a library and I need to write my own JS to add its behaviors to page elements), or does it add behavior all on its own, if specific ID or class names are present in the HTML? I have no idea, because that file is undocumented. A high-level overview would again be a good start.

[pjackson28]

@jpmckinney Okay, so a listing of the classes with brief descriptions. Where would be a logical place to house this? There are the classes that are common across themes and those that are theme-specific. Would it make sense to have it all in the design guide (with core and theme-specific sections) or to have core classes in a new core documentation and then theme-specific classes in the theme documentation?

As for JS, wet-boew.min.js includes a small core, with a loader, and all the plugin JS (excluding dependencies). The plugins are already described in the plugin documentation and to some extent in the design guide. We currently lack documentation about that small core but would be good to have it documented, including the available helper methods.

[jpmckinney]

The JS docs I know of are at http://wet-boew.github.io/wet-boew/docs/ref/plugins-en.html If there are JS docs in the V4 style guide, they're well hidden!

Right now there's no clear path through the documentation, so I don't know of an ideal place to put that page. So, a link from each of these pages would probably maximize the likelihood that people find it:

• http://wet-boew.github.io/wet-boew/docs/index-en.html
• http://wet-boew.github.io/wet-boew-styleguide/v4/index-en.html
• http://wet-boew.github.io/wet-boew/docs/ref/themesstyle-en.html

Adding a menu item under "Implement WET" for this page would make it easy to find, too.

I think the common classes should take priority over theme-specific classes.

[thomasgohard]

Hi @jpmckinney. I completely agree with your points; this is something I've been wanting to do for some time. I should be able to jump back into WET-related things in a couple of weeks, after I close up this year's CodeFest. Would you be interesting in helping put together these missing pieces?

[jpmckinney]

Sure, I'd be happy to review and edit the eventual page for clarity - sort of as a "documentation tester".