Glossary entries: Rewrites, scope and audience

Hi there,

my name is Tobias and I would like to start contributing regularly to the MDN Web Docs. I started by translating some Glossary entries to German. While doing this, some questions came up – maybe someone can find the time to answer them:

  • While translating, I found some (original) Glossary entries that imo weren’t putting the term in a nutshell or even got it wrong. Where would be a place to discuss rewriting complete Glossary entries? I definitely do not want to do this without the backing of other people, though I am aware of the Wiki approach the docs take.
  • Also, I found the Glossary entries to be of very different scope – from one sentence stubs (e.g. PNG) to pretty extensive documentation (e.g. Grid). Any guidelines here on what a Glossary entry should provide, also in distinction to the Learn section. For what audience(s) should the Glossary entries be written?

I hope this is the right place to pose these (pedantic) questions.

Best
Tobias

https://developer.mozilla.org/de/profiles/tschach

Hi Tobias, and welcome to MDN! Thanks for your interest, and efforts to contribute to the site, much appreciated.

To answer your questions:

  1. If you do find a glossary entry where you think the English version is wrong, I’d be happy for you to improve on it. If you want to discuss it with us first, or want us to review your work, a good place to contact us is the MDN admins e-mail address — mdn-admins@mozilla.org.

  2. Yeah, an issue here is that we never really enforced a rigid structure for the glossary entries to take, one reason being that different terms need different approaches to explain them. Generally entries should consist of a short explanation of the term, followed by an example and a bit of expanded information if needed, and then a “Learn more” section at the end to provide links to more in-depth information, but you do see some variation.

I’d say that good glossary entry examples include:

The PNG entry works, but is a bit short. It could do with some expansion on how common PNG is and browser support, typical kinds of image it is useful for, etc.

The grid entry is a little long, but not too bad. It could do with a concise explanation of what a grid is in general design, then go on to say that the CSS grid spec allow grids to be used easily on web pages. Some of the more detailed info and the example could be cut down, as that stuff is explained in the further reading pages anyway.

Anyway, I hope this helps! Feel free to keep asking those questions. We don’t mind pedantry here — we are a community of tech writers after all :wink:

1 Like