Wiktionary talk:Template documentation

This is a Wiktionary policy, guideline or common practices page. Specifically it is a policy think tank, working to develop a formal policy. Policies – Entries: CFI - EL - NORM - NPOV - QUOTE - REDIR - DELETE. Languages: LT - AXX. Others: BLOCK - BOTS - VOTES.

Originally from Template talk:en-infl-reg-vowel-e.

Summary

(The following summary is by Rodasmith:)

There has been a constant demand for more, better, and more clearly organized template documentation, but Wiktionary has no policy regarding where to put such documentation. Two common methods follow:

1. Document templates inside <noinclude/> sections of templates.

   Supporting argument: It is the most common method currently in use at Wiktionary and the location is inconsequential. (If it proves to be a load on the servers, then we'll simply have to move them to talk pages.)

2. Document templates on the template talk pages.

   Supporting argument: Doing so is consistent with Wikipedia (e.g.: w:Template talk:cite web) and reduces server load.

Your input on how to document templates is welcome at Template talk:en-infl-reg-vowel-e/Template documentation. Rodasmith 19:52, 19 April 2006 (UTC)

Now at this very page. — Vildricianus 11:45, 21 April 2006 (UTC)

Detailed discussion

A month or two ago, I started including template documentation inside "noinclude" sections of the template. I am no longer convinced this is the best way to go, as it makes the server work overtime for each instance the template is used. Is there active discussion about this practice anywhere that I am unaware of? --Connel MacKenzie T C 16:01, 19 April 2006 (UTC)

I had created documentation here [1] and on Template talk:en-verb [2], ala the standard template documentation style at Wikipedia, but my Wikipedia-style template documentation table of contents formatting was reverted [3]. Subsequent conversation informed me that Wiktionary template documentation belongs in <noinclude/> tags on the main template page.[4] So, I moved my documentation from the talk pages as recommended. Please let me know if there is a policy on where to put template documentation. Rodasmith 17:03, 19 April 2006 (UTC)

I am certain there is no policy. I doubt there is consensus on what our current practice should be. I guess this belongs {sigh} in the Beer Parlour as a new discussion topic. --Connel MacKenzie T C 17:07, 19 April 2006 (UTC)

Those reverts look troublesome. I'll ask other sysops if they agree that User:V-ball should be blocked. As a dictionary, we have built-in redundancy nearly everywhere. And the TOC directives are a no-no. --Connel MacKenzie T C 17:09, 19 April 2006 (UTC)

Wow, really didn't mean to do something that could get me blocked.  Sorry.  Anyway, as far as the format goes, I'll just put my vote in for option 1, the tags.  I just think this looks better and avoids the redundancy (yes, I know it exists, I'm somewhat familiar with dictionaries, but it wasn't just redundant) and the confusion of a TOC that lists stuff above it.  One of my complaints with Wiktionary and Wikipedia is the lack of usability, and a TOC below content listed in that same TOC just doesn't make sense to me.  Anyway, sorry about the nasty edit . . . I really didn't mean any harm, and again, I'm for sections. — V-ball 01:07, 20 April 2006 (UTC)

• There's absolutely no reason for blocking here; from what I've seen before, V-ball appears to be a well-intended person.
• I don't think it matters where the documentation is. If it proves to be a load on the servers, then we'll simply have to move them to talk pages. That's no big deal, is it? — Vildricianus 17:50, 19 April 2006 (UTC)

As a dictonary, we are redundant in many ways - nearly as a rule. In my short history here at en.wikt: there has been a constant demand for more, better and more clearly organized template documentation. The notion that wholesale removal of helpful information is itself somehow helpful is the opposite of what I've learned about wiki. So, the tremendous philosophical chasm between me and this so-called "well-intentioned" contributor may have caused me to over-react.

"Template documentation style" needs a calm, neutral discussion on WT:BP. For my part, I think I've possibly blown the "calm" and "neutral" aspects, so I'll try to stay out of it, as long as 1) server performance is discussed, 2) my previous efforts/experiments aren't misrepresented. --Connel MacKenzie T C 18:21, 19 April 2006 (UTC)

Fine, bring it on then. I don't see any problems here, but that'll be because I've no idea of previous discussions on this. — Vildricianus 18:28, 19 April 2006 (UTC)

My view is that the <noinclude> mechanism is a brilliant idea. It enables the documentation to be held as close as possible to the template itself, with the most chance to be correctly updated with the template. Can't believe it would place much real load on the servers. --Richardb 13:22, 16 May 2006 (UTC)

Additional posts to appear on including pages

This discussion sub-page is included in WT:BP and Template talk:en-infl-reg-vowel-e. Posts in the #Detailed discussion section will appear only on this discussion page. Other posts will appear in the including pages, adding to the size of WT:BP which is already too large for editors with slow connections.

Inflection, conjugation, and declension template names

[[:Category:Inflection templates]] are used immediately after the POS header to show the headword and a brief summary of its key forms. Most are named with the language code, a dash, the part of speech, and the inflection class (e.g. {{en-noun-reg}})), but some also include "infl" (e.g. {{en-infl-reg-other-e}}).

Most Category:Conjugation and declension templates contain "-conj-" or "-decl-" in their names and are used in a separate section to show a table of the headword's various forms.

Unfortunately, some templates (e.g. {{nl-noun}}, {{sv-noun}}, and {{fr-infl-adj}}) blur the separation of the two template types by having inflection-template-like names but displaying as a declension table.

For consistency, I propose the following naming conventions for inflection, conjugation, and declension templates:

• Inflection templates are named with the language code, followed by a dash and the part of speech, followed optionally by a dash and the inflection class.

  Examples: {{en-noun-reg}}, {{fr-adj}}

• Conjugation templates are named with the language code, followed by "-conj-", followed by the conjugation class.

  Examples: {{la-conj-1st}} and {{es-conj-ar}}

• Declension templates are named with the language code, followed by "-decl-", followed by the declension class.

  Examples: {{de-decl-noun}} and {{la-decl-3rd}} after their language code.

For yet more consistency, I hope we can decide whether the inflection line should consistently display as a table (like {{en-noun2}}) or like a traditional dictionary inflection line (like {{en-noun-reg}}). I expect that issue has been discussed at length to no resolution. If we have agreed to disagree regarding the traditional/table style for inflection lines, I propose we use CSS magic to allow users to choose whether they want to see tables. How does that sound? Rod (A. Smith) 19:33, 27 May 2006 (UTC)

Fine, but {{nl-noun}} is an inflection template, for usage on the inflection line. —Vildricianus 19:51, 27 May 2006 (UTC)

Great. I was confused because it displays a declension table. I suggest moving the declension table from it into {{nl-decl-noun}}, which would display in its own "Declension" section to match the format of languages with large declension and conjugation tables. I'd be quite happy to do the work, but I think I need approval before I start splitting up templates like that. Does that sound OK to you? Rod (A. Smith) 20:51, 27 May 2006 (UTC)

I see you're meaning to introduce more uniformity across languages. I can only encourage that :-). I thought the table to the right of the inflection line was pretty nice, but it's probably equally nice in its own section. —Vildricianus 00:13, 28 May 2006 (UTC)

Documentation of template sets

Some sets of template have their documentation on a page of the Wiktionary space. ????E.g. [[Wiktionary:Inflection templates]] documents [[:Category:Inflection templates]]????. It seems that the category page itself might be a better location for such documentation. Otherwise, the list of templates in the category can easily grown >out of sync with the documentation. Is there a specific reason not to document sets of templates within the templates' category page? Rod (A. Smith) 20:33, 15 May 2006 (UTC)

A cautionary note on the proliferation of templates.

I can remember back to when I started. I found some parts of Wiktionary almost unintelligible (when it came to editing) becuase of the complex use of templates. I think the idea of trying to make everything uniform is fine, but must be tempered with a recognition of the complexity it brings in for beginners.

For example, I can see sod all value in the "serial commas" kind of template, just added complexity for the satisfaction of someone playing with himself. It just isn't needed.--Richardb 13:17, 16 May 2006 (UTC)

It's not the quantity of templates that causes difficulty for newcomers, but rather the quantity of fundamental guidelines required to learn, the inconstist template usage patterns, and the lack of template documentation that makes it difficult. Nobody needs to understand or use all of the templates, just as nobody needs to understand all of the WikiMedia magic words or parser functions. The primary use for esoteric templates, WikiMedia magic words, and parser functions should be in other templates, well-hidden from newcomers.

Perhaps the key barrier for newcomers is the monumental task of learning how to create a proper entry from scratch. Preloads for new entries can simplify that, just as simple, consistent template names with obvious usage patterns can simplify editing of existing pages. We should identify, list, and correct the causes of each point of confusion. Rod (A. Smith) 16:44, 16 May 2006 (UTC)

Wiktionary:Index to templates

Wiktionary:Index to templates is also used to document templates.--Richardb 13:19, 16 May 2006 (UTC)

It seems that the content currently on Wiktionary:Index to templates should be moved to Category:Templates for consistency. Then the following pattern emerges:

• Each template is documentated in its "<noinclude/>" section (e.g. Template:en-infl-reg-consonant).
• Questions, comments, and general discussion for each individual template is on the template's talk page (e.g. Template talk:en-infl-reg-consonant).
• Each category of templates is documentated in the template category page (e.g. in Category:English headword-line templates (was [[:Category:English inflection templates]])).
• Questions, comments, and general discussion for each category of templates are on the template category's talk pages (e.g. in Category talk:English inflection templates).

I have included "Wiktionary:Inflection templates" in Category:Headword-line templates (was [[:Category:Inflection templates]]) to demonstrate how such documentation might appear if we use the above template documentation organization model. Rod (A. Smith) 16:44, 16 May 2006 (UTC)

From the Grease pit

I'm not sure what the last discussion resulted in. I read again, and found that there hasn't been much discussion. I'm sure though, that perhaps a heavily-used template, like {{wikipedia}}, could do without the extra strain on the servers each time it is edited. Documentation tends to get edited once in a while, so perhaps it's not unreasonable to keep it on the talk pages after all. The thing I have in mind is that, each time a template gets edited, the server caches need to be refreshed (am I right here?), so when we're talking about {{wikipedia}}, that are 15,201 pages that need refreshing. Is this a real strain? I don't know. It's something that didn't get said last time so I say it now. I also want to mention that it may not be unwise to (semi-)protect these templates for the same reasons. The upcoming English inflection templates are the ones that reminded me of it, as they may quickly become the most heavily used ones here. — Vildricianus 22:03, 2 June 2006 (UTC)

Yes, the server doesn't know that the changes were only in a "noinclude" section, so the template is marked as "dirty" and every page that uses it is queued for regeneration. I'd support moving the documentation to the template talk pages. We can also change {{temp}} to point to templates' talk pages and have a "noinclude" note at the top of each template to mention that the documentation is in the talk page. Rod (A. Smith) 00:46, 3 June 2006 (UTC)

We should really file a bug report / feature request on this. It shouldn't be too hard to figure out if an edit to a template would affect caching. At the very least a dev would respond to our concern about wasting server power. — Hippietrail 22:37, 4 June 2006 (UTC)

I think posting to wikitech-l would be even better. — Vildricianus 22:42, 4 June 2006 (UTC)

This is tricky. The command msgnw uses aspects within the noinclude, so the template would still have to be marked as dirty. Of course it would make sense to have msgnw NOT include sections within noinclude, but from the spaghetti-like consistency of this language I doubt anybody likes win-win revisions. You also have to be careful to count includeonly's when comparing changes because their placement can affect evaluation. Davilla 15:07, 5 June 2006 (UTC)

I'm not sure there was any serious debate regarding the noinclude style documentation vs. the talk page documentation. I know I always used the 'noinclude' style only because I'm lazy. (Lazy in the good way...lazy programmers == code reuse.) But now that there is evidence that this style of documentation is harmful, it only makes sense to correct it, procedurally, from now on. Right? --Connel MacKenzie T C 05:54, 9 June 2006 (UTC)