Page MenuHomePhabricator

Publish best practices on MediaWiki.org concerning glossaries
Closed, ResolvedPublic

Description

Potpourri of my last thoughts and searches about that glossary, initially published on T129088#2776731.

Definition lists

Definition lists on HTML are implemented on MediaWiki.

A structure like

;Defined term
:Definition

is parsed as

<dl>
<dt>Defined term</dt>
<dd>Definition</dd>
</dl>

That's cool and accessible.

Synonyms

All documents say the same thing:

;Defined term
;Synonym at same level
:Definition

But there is no visual distinction between a preferred term and a synonym.
The best we can do is to add a note (example) but that's not the best option we can have. Plus, we don't know if it is accessible?

English Wikipedia manual of style advise to add an "also" line in the definition:

;Defined term
:also known as Synonym
:Definition

The also known would have a different styling that will feat to most of our readers, the "also known as" would be bonus for the accessibility. I think that's the best we can do.

Language specific synonyms

I think the synonyms translations should be open to translations. Translate some terms from English to an other language are not always accurate, plus some communities may have created a specific term for a specific feature. That's good because it shows that the product is adopted by communities.

The idea would be to have the translation of the synonyms remaining open. That way, people will not have to translate the English terms but will have a space where they can add the terms used in their language. This will systematically be documented on the qqq documentation language.

Template or not template?

That's the question.
That would help, but it may complicate the translations marking. Plus, templates are not always friendly with RTL & LTR. Based on that, the only template we can have will style the synonyms.

To do

  • Create a page to document how to create glossaries the best way
  • Create a template for qqq, to tell translators that they have to adapt the synonyms

Event Timeline

You say "best practices", I think Technical-Collaboration-Guidance, at least being linked from the right places. Thoughts?

You say "best practices", I think Technical-Collaboration-Guidance, at least being linked from the right places. Thoughts?

If operational practices can fit to the TCG, why not.

Keegan added a subscriber: Keegan.Nov 9 2016, 6:07 PM

I'll look over the page and see if/how it fits in with the TCG.

I'll look over the page and see if/how it fits in with the TCG.

So?

I've left a message on PD help project talk page on mw.org about this page.

This comment was removed by Trizek-WMF.

Right, while this shares words with the TCG like best practices, I find its purpose to be different from the TCG. Namely, I don't see this is a systemic part of community engagement around software. It can live on its own.

Trizek-WMF updated the task description. (Show Details)Nov 28 2016, 2:55 PM
Trizek-WMF closed this task as Resolved.

My to-do list is done for that. No feedback received so far, so, let's be bold and move on: I remove the draft tag on the page and close that task. A subtask is created to unify the documentation.

Qgil awarded a token.Nov 28 2016, 9:41 PM
Johan moved this task from Backlog to Archive on the User-Johan board.Jul 26 2017, 3:27 AM