Page MenuHomePhabricator

Document WikimediaUI Base's font stacks, the research and reasons for each choice
Closed, ResolvedPublic

Description

I have documented the information I've found out while doing the parent task, so people after me don't have to go through the hoops again.
It seems the wikimedia-ui-base project is the current state-of-art in general design questions, thus this documentation would belong there.

This includes 1 file:

Questions
  1. What the documentation file name should be? I propose README-fonts.md
  2. Which folder should host it in Core?
    1. '/docs'
    2. '/resources/lib/ooui/' -- next to the WMUI Base's 'wikimedia-ui-base.less'
    3. '/resources/src/mediawiki.less/' -- next to the import wrapper of 'wikimedia-ui-base.less'

Patches have been submitted.
The 2nd folder has been chosen: '/resources/lib/ooui/'

Event Timeline

Please raise your questions or concerns - if any - before I start working on a patch and give a confirmation for the file name.

Change 571944 had a related patch set uploaded (by Aron Manning; owner: Aron Manning):
[wikimedia-ui-base@master] Document WikimediaUI Base's font stacks, the research and reasons for each choice.

https://gerrit.wikimedia.org/r/571944

Change 572947 had a related patch set uploaded (by Aron Manning; owner: Aron Manning):
[mediawiki/core@master] Document WikimediaUI Base's font stacks, the research and reasons for each choice.

https://gerrit.wikimedia.org/r/572947

Thanks, I've merged it into the documentation, converted to wikitext and uploaded.

This task still fails to outline what the problem is, that it tries to tackle.
It goes into providing a solution without clarifying what is wrong/missing currently.

This task still fails to outline what the problem is, that it tries to tackle.
It goes into providing a solution without clarifying what is wrong/missing currently.

Obviously, the lack of documentation. Does that need a more extensive explanation than "Document the font stacks and the choices made"?

@Volker_E Thank you for your comment about design documentation being moved to http://design.wikimedia.org/style-guide
I think the documentation that I've written - detailing the history of these design decisions - is too much in-depth and technical to be presented on that site.

My concern is that it took me ca. two weeks of research to find out about this history and in the meantime, you had to spend time answering my cards that lacked awareness of this information. I'd like to save that 2 weeks for other people in the future and provide easily accessible documentation that doesn't need searching on-wiki. This was the motivation behind summarizing this history and presenting it where it's needed: next to the code.

I've also converted it to wikitext and uploaded at https://www.mediawiki.org/wiki/Wikimedia_User_Interface/Use_cases/Font_family_stack , but that page is uncataloged and impossible to find.

I wish to finish this documentation project and add it where it's trivially accessible for anyone who's looking for the reason behind these font-stack definitions. What's left is to find the proper place for it.
The most obvious place would be next to the wikimedia-ui-base.less file, which I've considered initially, but the docs have their own folder, so I've moved it there.
The choice itself is not as important as to actually make the choice, therefore I'm awaiting your advice.

To accommodate your request the documentation has been moved to '/resources/lib/ooui/' next to the file 'wikimedia-ui-base.less', which it documents (patch).

Change 577780 had a related patch set uploaded (by Aron Manning; owner: Aron Manning):
[mediawiki/core@master] Add documentation for the font stacks

https://gerrit.wikimedia.org/r/577780

Just adding a belated response, repeating my take on patch set 8 to your comment in T244790#5901026 – I don't think any of the code places is the right one. These extensive code documentations, see your next task T244794, get too easily out of sync leading to more confusion when developers are in interest to search for explanations. https://www.mediawiki.org/wiki/Wikimedia_User_Interface/Use_cases/Font_family_stack updated is already pointing at a better place for such, while still too verbose in my personal opinion.

Change 571944 abandoned by VolkerE:
[wikimedia-ui-base@master] Add documentation for the font stacks

Reason:
As this file mentions itself “This document on-wiki”, all the documentation here is a mirror of https://www.mediawiki.org/wiki/Wikimedia_User_Interface/Use_cases/Font_family_stack and we don't need to repeat the same information in n places to keep ourselves busy.

https://gerrit.wikimedia.org/r/571944

Change 577780 abandoned by VolkerE:
[mediawiki/core@master] Add documentation for the font stacks

Reason:
Not only has this been added in the wrong location, it's also a mirror of https://www.mediawiki.org/wiki/Wikimedia_User_Interface/Use_cases/Font_family_stack, which has been referenced in latest PR for Design Style Guide's Typography section https://github.com/wikimedia/WikimediaUI-Style-Guide/pull/396 – hence abandoning

https://gerrit.wikimedia.org/r/577780

Not duplicating documentation in our low-resource environment is a far more success promising approach than dupli- or triplicating documentation. With amendments of the Design Style Guide and links in WikimediaUI Base variables this should be resolved. Thanks to @Demian for the inputs.