Wikipedia talk:Manual of Style/Glossaries/Archive 1

Archive 1

2008

Rationale

Resolved

 – Moot. All of the points of debate are regarding a draft that looks nothing like the present document. Remaining issues should be raised in new threads.

There are more and more glossaries in Wikipedia all the time, but heretofore no glossary-specific style and naming guidance, only style guidance about stand-alone lists generally and naming guidance about long lists generally. This draft guideline attempts to do all of the following:

1. Provide basic style and naming conventions guidance with regard to glossaries.
2. Summarize basic content guidance as well, by reference to WP:NOT, etc.
3. Agree with all relevant extant guidelines, and make reference to them, and document reasonable variances (e.g. where non-glossary list style and glossary style do not logically agree, how the logic of WP article size is not properly applicable to glossaries, etc. – that last exception should also be ported to WP:SAL).
4. Enumerate exceptions to this guideline and why exceptions are justified, so that the guideline is neither too rigid nor sanctioning of ignoring its recommendations without reason.
5. Provide a consistent way of creating glossaries (present practice is all over the map).
6. Use HTML properly to lay out glossaries - WP pages should validate.
7. Lay out glossaries in a semantically-rich manner.
8. Lay out glossaries in a way that is supportive of accessibility.
9. Document how to work around known MediaWiki bugs and problems.
10. Show how to use glossary style with non-glossary lists (a use of the definition list elements that is explicitly sanctioned by the HTML specs).
11. Provide basic templates and examples – one should be able to create a glossary by simply copy-pasting from this guideline and adding content.
12. Distinguish between in-article glossaries and stand-alone glossary list articles.

— SMcCandlish [talk] [cont] ‹(-¿-)› 22:10, 22 September 2008 (UTC)

I see no need for this page. Several of its provisions, chiefly not capitalizing entries, contravene good English style. Septentrionalis PMAnderson 02:03, 23 September 2008 (UTC)

In what way does that contravene good English style? I don't see any evidence of that at all. In fact, I find it pretty rare to see glossary entries capitalized in print. The simple fact of the matter is that if you capitalize a glossary entry, the only hint to the reader whether the term is a proper noun or not is how it looks if the term is re-used in the definition itself (which is generally considered bad style in its own right). Looking through Chicago, for starters, I can't find anything at all that suggests capitalization here. And maybe more to the point, you've used a form of weaselwording here, in suggesting that "several of its provision" contravene good English style, while only drawing attention to a single (specious) example. The implication is that the this draft is riddled with holes, yet you only point out something that isn't actually a hole at all. — SMcCandlish [talk] [cont] ‹(-¿-)› 06:31, 23 September 2008 (UTC)

Anderson, you're still chained to the typewriter era (where caps and bolding were all we had)? Computers offer so many ways to highlight that we have loosened up on capitalisation for the sake of it. I don't mind it here, since three hightlighting methods are already used: lineage, indenting and bolding.

[unsigned commented posted by Tony1 (talk · contribs), 02:24, 23 September 2008 (UTC)]

I see no reason, no sources, and no policy, which encourage us to re-invent English. Those inventive souls who wish to do so would do better to obtain genuine consensus - not the usual cabal in a corner, who make up whatever crackpottery they like. Septentrionalis PMAnderson 03:26, 23 September 2008 (UTC)

Reasons: 1) We have glossaries. They are wildly inconsistent, and many of them coded really badly. Time for consistency. 2) WT:MOS has been notified that FA reviewers are at a loss for what to do with glossary list articles, because they don't really fit the mold offered by WP:SAL. They're a related but different species, for which no guidance of any kind has been offered to date. That's plenty reason enough. Sources: Huh? This isn't an article. What sort of sources would you want to see cited? I've cited everthing that appears to be relevant and citable, including the HTML specs on definition list markup, and WP guidelines on style and naming conventions of lists. Policy: Huh? What are you talking about? Wikipedia policy concerns itself with basic operational viability (WP:CIVIL, WP:V, WP:DP, etc.) and legal matters (WP:COPYVIO, WP:BLP, etc.) Neither of these are relevant in any way to question of how to format glossaries, any more than policy is relevant to what we do with kB vs. KiB, or what to italicization should be reserved for, or what a lead section should look like. PS: It's not like I didn't expect you to be the first to show up and vociferously oppose, because you are opposed to glossaries in general; I did at least expect something akin to cogency, however. PS: There is no "reinvention of English here". Please drop the hyperbole; it is not conducive to consensus building. If your only concern (it is the only one specifically mentioned so far) is that terms be sentence-capped, then make a case for that. — SMcCandlish [talk] [cont] ‹(-¿-)› 06:31, 23 September 2008 (UTC)

My main issue is that in a period when we're trying to rationalise the MoS sprawl, is it not possible to integrate this into an existing MoS page? Has this been notified at WikiProject MOS? A few specific issues:

• Glossary: "A list of". The first "and" is used on purpose, I presume (it shouldn't be "or", I'm assuming). When you say "a similarly formatted list", do you mean any list of terms and definitions? In the example, are "airplanes" akin to "terms", and "serial numbers" to "definitions"? This needs clearer wording; I'd remove the parentheses.
• Is this pitched at dummies like me? If so, you're partly in a teaching role, or at least holding our hands as you walk us through it. For DL et al., can you link us to an example, or provide one on the spot (as you've done for "Glossary formatting"? I wonder whether a single example could be provided that illustrates by direct association the second to the fifth terms. Tony (talk) 02:24, 23 September 2008 (UTC)

Integration: This began as a draft modification to WP:SAL, but there is (I would argue) too much to cover. SAL and WP:NCLL would certainly be updated to summarize the salient points here (with a {{More}}), but I'm pretty hard-pressed to come up with a way to simply integrate this wholesale into SAL or anything else without making the merge target bloated. This is simply an entire class of article that MOS has just ignored for years.

The rest of your concerns seem to be about the terminology table, which I must confess dates to a more confused and complicated version, and should probably just be deleted. I'll delete it now, actually. PMAnderson changed it all before I could get around to it; let's see how that version goes. On a re-read, none of the terms are confusing in-context now (they used to be, a day and a half ago). So, with that gone changed, would it it still come across as confusing or overly technical? In answering that, please keep in mind that MediaWiki has quite severe bugs that have to be worked around, such that dealing with glossaries is pretty much necessarily a tad more complicated than just writing plain prose. The gist is that this is the format, and it will work:

{{gloss}}
{{term|TERM HERE}}
:DEFINITION HERE
{{glossend}}

and that some other geekery is needed if people want to get really fancy. Oh, and that people can actually get away with simply:

;TERM HERE

:DEFINITION HERE

but someone should convert that, to stop MediaWiki from doing idiotic things in the code. Any better? PS: Yes, I did post a notice at WT:MOSCO; I'm not trying to ramrod anything; this is labeled just a proposal, after all. :-) — SMcCandlish [talk] [cont] ‹(-¿-)› 06:31, 23 September 2008 (UTC) PPS: By "a similarly formatted list", I was trying to get at non-glossary lists that are formatted in glossary style (something that, for whatever reason, is emphatically countenanced by the HTML specs with reagard to DL/DT/DD). The extant prose original prose, before PMAnderson deleted over half of it already covers covered all of that, though, so the confusing terminology stuff can just go away. Maybe. We may have taken a step backward here. — SMcCandlish [talk] [cont] ‹(-¿-)› 06:38, 23 September 2008 (UTC) Updated 07:22, 23 September 2008 (UTC), — SMcCandlish [talk] [cont] ‹(-¿-)›.

Why is this in Wikipedia space at all?

Resolved

 – Proponent of userspacing has not replied in over 1.5 years; page has multiple significant editors now anyway.

This is the opinion of one editor. Let it be moved to userspace until it gets some support at least. Septentrionalis PMAnderson 03:33, 23 September 2008 (UTC)

Say wha'? Why would I move a proposal to userspace, when the entire intent is for people to look at it and add to it and mold it, and I've asked for this at both WT:MOS and WT:MOSCO; especially given that 99% of editors will not even think of touching the text of something that is in userspace? Are we on different planets or something? Look, I'm sorry that you have made it clear that you think that all glossaries in Wikipedia are worthless and should be replaced by links to Wiktionary (which of course won't actually contain any of the topic-specific information that well-written Wikipedia glossaries have, but let's pretend). There is no consensus on Wikipedia that encyclopedically-written glossaries cannot exist here, despite the efforts of you and a couple of others to assert the opposite from time to time. If you wish to change the actual status quo to a community-wide position against glossaries entirely, then take it up at WP:VP; this is not the venue for it. Given that glossaries do in fact exist here, there should be a guideline on how to do one properly. Every article here should strive for featured status, and we even have a featured list process. WT:MOS recently got visited by someone from these processes saying "hey, we don't have any guidance at all on what a WP glossary should be like". This is a first draft at that, with a strong eye to agreeing as much as possible with extant guidance with regard to lists. If you have (a) substantive objection(s) to something(s) in the draft, instead of this diffused, general negativity, then please get specific and suggest constructive alternatives. — SMcCandlish [talk] [cont] ‹(-¿-)› 06:00, 23 September 2008 (UTC)

Too much information lost

Stale

 – Discussion died off over 1.5 years ago.

PMAnderson, I can see where you are going with the recent scalpel-in-hand edits and (ignoring the outright personal attacks, like "blatant imbecility"), can probably work with them, but in some cases you have mistaken technical facts for personal preferences and lopped out necessary details. I'll try working on this again on Wednesday. What you've recast as "structured glossaries" (a term I actually like) have considerably more stringent requirements than your version admits. MediaWiki really does have some genuine problems in this area that have to be worked around carefully, because the software simply is not flexible at all here. I also object to your deletion of most of the explanatory and exemplary material in this draft, since as we all know only too well, editors generally will not follow guidelines they do not understand or do not feel to be justified. — SMcCandlish [talk] [cont] ‹(-¿-)› 07:13, 23 September 2008 (UTC)

They're not attacks on you; they're attacks on the existing prose. (Nevertheless, having made my opinion all too clear, I will tone it down.) I support explanatory sections; I support examples; and if I have removed anything which adds substantially to the article, please do add it back. I intended to remove only duplications, redundancy, and commands. Septentrionalis PMAnderson 01:13, 29 September 2008 (UTC)

Okay. I think one place we may need to have a discussion is the notion of redundancy. While I agree that redundancy within the page should be eliminated anywhere it is not completely essential (which, really, means it should almost always be eliminted; redundancy is rarely needed in MOS pages, except where the interplay between one section and another may not be obvious to most editors). Redundancy between guidelines should also be eliminated, when it is purely redundant. One problem of many MOS and NC pages is that they often simply state their particular micro-case, without relating the specific advice/convention (disambiguation of human names, use of en-dashes, whatever) to general MOS/NC principles. I have been endeavoring to do this here, to show how a general bit of guidance is specifically applicable to this kind of case. I'll try to be clearer about that as we move forward. — SMcCandlish [talk] [cont] ‹(-¿-)› 21:42, 1 October 2008 (UTC)

If more explanation is necessary, what would help is explanation of what damage, exactly, unstructured glossaries do to the XHTML code. It is not at all obvious what it would be; or, since it's not intended to be human-editable, why we need care about some frms of elegance. Septentrionalis PMAnderson 01:13, 29 September 2008 (UTC)

Good point. I'll try to do that better as well. — SMcCandlish [talk] [cont] ‹(-¿-)› 21:42, 1 October 2008 (UTC)

I think in general S McCandlish and I agree that glossaries can be unstructured; but he doesn't say it very noticeably, because he thinks all glossaries should eventually be structiured. I would like to see the semantic web actually become prevalent first. Septentrionalis PMAnderson 01:13, 29 September 2008 (UTC)

Yes, I do; the interplay between [X]HTML per se and the results of wikimarkup is often pretty grotesque, but those problems can be worked around.

This isn't just about the semantic Web, but about many other things, including cross-browser/cross-platform consistency of content presentation, ability to re-use Wikipedia content in multiple ways (a day-one goal of the project), accessibility, future-proofing, etc. NB: Whenever Web semantics are mentioned, that is a reference to semantic markup in general. The semantic Web is only one consequence of semantic markup. Others include ease of maintenance and of transition to future versions of HTML, transformation via XSLT into other XML-based content markup schemes for other uses, or into other markup languages entirely (PostScript, RTF, whatever), practicability of embedded microformats, clean separation of presentation and content, improved accessibility, a more structural approach to content editing, and so on. Semantic markup is already prevalent, except among amateur websites that are coded the most expedient way possible to get something that looks right in MSIE or whatever the author's favorite browser is. This stuff isn't new; it's been in the specs since HTML 3, and increasing from geeks-only to dominant starting around 1996.

As for the MediaWiki problems, "have the developers fix it", if that was to be the next suggestion, isn't really a viable option for the short term. This will certainly be pursued, but it's become abundantly clear that the devs will generally not fix things that are only bugs from the content-markup and -presentation perspective; even if given patches, the patches just sit there unapplied, sometimes for years, while the devs work on adding new features. Over the longer haul, what needs to happen is that the ";" and ":" wikimarkup needs to stop using dl/dt/dd, and instead use divs that happen to look just like those dt's and dd's output, so that the glossary markup is literally only used when it is manually inserted on purpose. Then that code needs to be fixed, because for example MediaWiki does not implemented it properly as flow-type content (i.e. it can be inline or block - it can just be a sentence, or it can contain paragraphs, with block quotations and lists and so forth), none of more complex cases being supported by MW right now unless whitespace is collapsed between the block elements. It's clearly an outright bug, an implementation failure. — SMcCandlish [talk] [cont] ‹(-¿-)› 21:42, 1 October 2008 (UTC)

[outdent] Update: The article I really wanted, to explain the importance of semantic markup, didn't exist then, but now does: Semantic HTML. It should make much more, and much more grounded, sense to you, if you're still interested in any of this a year and a half later. — SMcCandlish Talk⇒ ʕ(^Õل^ō)ˀ Contribs. 02:52, 12 June 2010 (UTC)

Wiktionary

Resolved

 – Obvious WP consensus against deleting glossaries from Wikpedia simply because copies of them exist on Wiktionary.

Wiktionary has 108 pages in wikt:Category:Glossaries. Don't pure glossaries which merely provide definitions belong there? —Michael Z. 2008-09-23 17:41 z

They're there largely because a Wiktionarian goes around and copies them to there from here. He's asserted sometimes that this means they should simply be deleted from WP, but of course if you actually look at their contents they fork very rapidly, with the WP versions being sourced and developed, and the WK ones just sitting there unchanged. The fact of the matter is that there not only is no consensus against glossaries in Wikipedia, attempts to AfD them routinely fail, [1][2][3] and the Featured List process accepts them as candidates.[4] The Wiktionarian's transwiki notice template used to advocate AfDing transwikied glossaries, but this did not sit well with various editors here, and it has long since been changed to no longer do that (and not by me, either; I have had no part in the dispute). Furthermore, Wikitionary does not have WP:V (or WP:RS). The preferred citation type on WK is just an example of usage, not a source for the accuracy of the definition, making glossary needs and intent completely different on the two wikis. Lastly, as this draft guideline would make clear, a WP glossary cannot simply be a list of dicdefs, per WP:DICT, making the question moot to begin with. — SMcCandlish [talk] [cont] ‹(-¿-)› 21:00, 24 September 2008 (UTC)

Update: As of quite some time ago, glossaries have been accepted as a clear and common example of a type of Wikipedia list, at WP:LISTS. This indicates an obvious consensus that glossaries are acceptable and normal on Wikipedia, within the bounds of other WP policies and guidelines. — SMcCandlish Talk⇒ ʕ(^Õل^ō)ˀ Contribs. 02:55, 12 June 2010 (UTC)

How-to

Resolved

 – Moot.

DanK suggested (elsewhere) that this could be a how-to (i.e. a "Help:"-namespace page). I think that the technical aspects of it could. This would reduce the verbiage here to simpler style guidance only, and probably make it small enough to merge with WP:SAL. — SMcCandlish [talk] [cont] ‹(-¿-)› 21:04, 24 September 2008 (UTC)

Barring any objections, I'm going to do this over the next day or so. I doubt there would be any dispute about it, sine the Help: page would basically just be factual information about specs, bugs and workarounds, easily verifiable with reading the specs and testing the code, as I've already done extensively. — SMcCandlish [talk] [cont] ‹(-¿-)› 21:01, 1 October 2008 (UTC)

Actually, I eventually decided I wouldn't do this. WP:LISTS and other list-related pages contain at least as much in the way of code examples, and this page is not any more howto-ish than they are. A Help:-namespace page could possibly be written later, but I think it would make way more sense to add glossary-related information to existing material, e.g. at Help:List. — SMcCandlish Talk⇒ ʕ(^Õل^ō)ˀ Contribs. 03:00, 12 June 2010 (UTC)

Verbal mood & voice problems

Resolved

 – Subsequent editing, e.g by SMcCandlish, Pmanderson and The Transhumanist, appear to have cleaned this up.

Instructions to the reader should address the reader directly with the Imperative mood. Currently the instructions suffer from too much Passive voice with missing actor. This forces the reader to mentally disambiguate the missing actors, for example to guess whether the instructions are telling the reader to do something, or describing an action by something or someone else. This slows comprehension and makes the instructions harder to understand. --Teratornis (talk) 03:51, 26 June 2009 (UTC)

Yep. I'm trying to fix most of the wishy-washy, non-imperative wording first, with passive voice cleanup on the backburner. The entire document needs restructuring, so I've been working on that mostly and doing imperative fixes along the way. — SMcCandlish Talk⇒ ʕ(^Õل^ō)ˀ Contribs. 03:07, 12 June 2010 (UTC)

Brevity vs. clarity

Stale

 – Discussion died, and others have been copyediting for 3+ years since this thread.

Thus, for instance, I am about to edit the section on splitting glossaries; I shall comment on each paragraph. I really don't see much useful content besides split into sections of the alphabet when the glossary hits 100K.

A glossary that becomes too long (more than about 100 kB) should be split into multiple articles. While normal Wikipedia articles are usually expected to be considerably shorter, glossaries and other lists are rarely read through from top to bottom (reader fatigue and ennui being a major article-length rationale), and are more useful the more easily they are in-page searchable. These are good reasons to not split an list article article unnecessarily. Overly-large articles, however, take a long time to load, even longer to load for editing, and yet longer to edit-preview, and may cause some browsers to crash due to the memory requirements needed to display them.

• Can be condensed to Split at 100K; not earlier because we don't expect readers to browse right through; but vey large articles have problems. Septentrionalis PMAnderson 01:28, 29 September 2008 (UTC)

Why would we want to reduce this to something that's only marginally grammatical in standard English? It reads like a newspaper headline. I agree the original was too long, but let's not go to the other extreme. I'm not sure why you seem to loathe rationales so much, but I think it has become very clear that editors will ignore or dispute anything in any MOS page that they don't initially like or agree with simply because they don't understand why it says what it does. This is the principle reason we get so many rehashed debates on the MOS talk page, an incredible waste of everyone's time. I agree it can be shortened, but not that much. — SMcCandlish [talk] [cont] ‹(-¿-)› 20:59, 1 October 2008 (UTC)

On a re-read, I believe that this super-shortened version will simply be non-sequiturial for most editors, who are not likely to have memorized the article length guideline and its rationales. — SMcCandlish [talk] [cont] ‹(-¿-)› 21:51, 1 October 2008 (UTC)

Splitting glossaries is different from forking content out of an over-long general article into specific sub-articles, as in summary style. Glossaries should be split in half (A–M and N–Z is the most common split point) if only marginally larger than 100 kb, or into thirds (A–H, I–P, Q–Z, for example) or even more pieces if substantially larger, or strongly expected to continue growing considerably. A glossary generally should not be split into a separate page for every letter of the alphabet, though single-letter pages may be warranted in special cases, such as when a particular topic has a great number of terms all beginning with the same letter (e.g. a split into A–R, S, and T–Z might be called for).

• The first sentence can be don't reduce glossaries into summary style; divide the alphabet. Septentrionalis PMAnderson 01:28, 29 September 2008 (UTC)

Yeah, needs work. But the proposed replacement is way too simple, saying nothing about how to do it, and the "how" is important. We do not want cases of a 200 kB glossary being split into 26 articles. You must know just as well as I do that someone (multiple someones!) would do exactly that given no advice other than to split alphabetically. This would then result in a big mess to clean up, and probably lots of bitching back and forth between parties about what the guideline "really means", etc., etc. Nip it in the bud now. Brevity is a writing virtue, but so are completeness and clarity, which should not be sacrificed in the name of the former. Prevention of predictable misinterpretations and disputes is not instruction creep or WP:BEANS. — SMcCandlish [talk] [cont] ‹(-¿-)› 21:15, 1 October 2008 (UTC)

• What if the glossary is 2600K? Then we want articles for each letter. Septentrionalis PMAnderson 01:28, 29 September 2008 (UTC)

Already implicit. — SMcCandlish [talk] [cont] ‹(-¿-)› 21:15, 1 October 2008 (UTC)

The first sub-article of a split glossary, e.g. Glossary of underwater basketweaving terms: A–M, should usually be the main article (i.e. Glossary of underwater basketweaving terms should redirect to it). However, if the glossary is truly massive (e.g. has more than 5 sub-articles), the main article name should contain the full lead and then a list of sub-articles, rather than the content of the first segment of the glossary proper.

• Can be rephrased to be much shorter. Septentrionalis PMAnderson 01:28, 29 September 2008 (UTC)

Doesn't need to be "much" shorter, though probably some. It is better that a guideline be clear and have examples that be as highly compressed as possible but easy to misinterpret (or difficult to interpret at all). This isn't a 30-second radio spot; we don't have to be so concise that people get headaches trying to interpret. — SMcCandlish [talk] [cont] ‹(-¿-)› 20:59, 1 October 2008 (UTC)

Regardless, subsequent sub-articles in the series should only summarize the lead from the first sub-article, not repeat it entirely (nor be devoid of any lead).

• Can be combined with first paragraph. Septentrionalis PMAnderson 01:28, 29 September 2008 (UTC)

Right. — SMcCandlish [talk] [cont] ‹(-¿-)› 20:59, 1 October 2008 (UTC)

Each sub-article must have its own references section(s), and care must be taken to ensure that references are cited properly in all sub-articles. For example, a <ref name="Foo 2007">{{Cite book|...source details...}}</ref> from the initial sub-article will need to be copy-pasted over the first occurrence of <ref name="Foo 2007" /> in subsequent sub-articles after a split.

• Make into warning on how to split a glossary. Septentrionalis PMAnderson 01:28, 29 September 2008 (UTC)

Concur. — SMcCandlish [talk] [cont] ‹(-¿-)› 20:59, 1 October 2008 (UTC)

Each sub-article must clearly link to the preceding and following sub-articles in the series (as applicable), or all of them if there is no particular order (which may be the case especially with non-glossary lists using glossary formatting), preferably in or near the lead. It is unnecessary to repeat this information in a ==See also== section. For typical long glossaries, this can be accomplished with the same {{CompactTOC8}} template already mentioned.

• shorten. Septentrionalis PMAnderson 01:28, 29 September 2008 (UTC)

To what? The points mentioned are all salient. — SMcCandlish [talk] [cont] ‹(-¿-)› 20:59, 1 October 2008 (UTC)

Any cleanup or dispute tags that apply to the glossary as a whole should be applied to all of its sub-articles. Such tags that apply only to a segment of the glossary should only be applied that sub-article only.

• Why do we need to say this? It applies to any branching article. Septentrionalis PMAnderson 01:28, 29 September 2008 (UTC)

Show me where any guideline says that. You are right that it isn't really a glossary issue, though. Sould be moved to WP:SAL. Not simply deleted. — SMcCandlish [talk] [cont] ‹(-¿-)› 20:59, 1 October 2008 (UTC)

Unless requiring their own sub-article(s), sections for numbers, symbols, or symbols and numbers should remain in the first sub-article, above section A.

• Do we need to make this point? Why? Septentrionalis PMAnderson 01:28, 29 September 2008 (UTC)

Yes, because some nimrod will put it at the end, where no one expects it, and where it won't match the order given by {{CompactTOC8}}, et al. I've already seen it happen (that is why I included it actually; it was a late addition). — SMcCandlish [talk] [cont] ‹(-¿-)› 20:59, 1 October 2008 (UTC)