Are our main audiences, designers and developers, well addressed by the current information architecture of the style guide?
This came out of a conversation with @JGirault pointing at the current structure.
I see the style guide as the language shared between designers and developers.
The current homepage doesn't yet contain a Resources section. But in our drafts, we split it the style guide such as:
Are the resources featured high enough?
Do we appeal to them in the text?
Do we have call to actions for them?
I think we can do better. For now we're not giving away concrete values that a developer can extract easily. But it's because it's a WIP and we are still iterating on it. The colors section is the one that contains real definitive values. There we can do more though, and give the equivalent wikimedia-ui-base variable names: @wmui-color-base20. I just made a pull request for that: https://github.com/wikimedia/WikimediaUI-Style-Guide/pull/25
Resources are fine at the bottom. However I think it is too late to split designers and developers.
If we stay too high-level and welcome them all with a common language, I worry the message is not as effective and we lose our audience.
I suggest to improve the first section this way:
@Nirzar shared http://carbondesignsystem.com/ with us and I think it's s very direct and helpful from a developer standpoint. It's a good inspiration.
@JGirault I agree with your statement about the missing direct shortcut to “Resources” on the homepage. That sounds like a good addition.
Here's a screenshot from your pull request
The devil lies in the details as we want to encourage developers not to refer to the color variables directly in their code, but building semantic color variables with them:
@background-color-base: @wmui-color-base100;
@JGirault I agree with your statement about the missing direct shortcut to “Resources” on the homepage. That sounds like a good addition.
Here's a screenshot from your pull request
I don't think this is the right direction as it's a lot of redundant information. I'd rather add a sentence above or below saying if you refer to the colors in code, please use the following naming convention exemplified on white: For CSS --wmui-color-base100, for Less @wmui-color-base100.
From my experience, most developers are lazy...
They look for a color, they go to the colors section, they find a color, and they want to copy/paste the value in their code. If they are mainly given the hex color, I can only think there is more chance they copy/paste the hardcoded value directly into their code. It may seem like redundant information, but it's probably the only information a developer would copy/paste from this page.
The devil lies in the details as we want to encourage developers not to refer to the color variables directly in their code, but building semantic color variables with them:
@background-color-base: @wmui-color-base100;
I see.
What about giving such recommended values @background-color-base: @wmui-color-base100; in the Components section... similar to http://carbondesignsystem.com/components/button/style.
@JGirault In my plan, developers should rely on WikimediaUI Base. And it's all already in there. They don't even have to (and probably won't go too) often to the style guide for such fundamentals.
We can't feature it currently because it's not merged yet.
This task has been assigned to the same task owner for more than two years. Resetting task assignee due to inactivity, to decrease task cookie-licking and to get a slightly more realistic overview of plans. Please feel free to assign this task to yourself again if you still realistically work or plan to work on this task - it would be welcome!
For tips how to manage individual work in Phabricator (noisy notifications, lists of task, etc.), see https://phabricator.wikimedia.org/T228575#6237124 for available options.
(For the records, two emails were sent to assignee addresses before resetting assignees. See T228575 for more info and for potential feedback. Thanks!)