Commons:Requests for comment/How Commons should deal with TemplateData
An editor has requested comment from other editors for this discussion. If you have an opinion regarding this issue, feel free to comment below. |
The need for a standardised way to store information about templates (i.e. their documentation, how to use them and what they do) led to the development of Extension:TemplateData. This page is to discuss how Wikimedia Commons should deal with TemplateData with the final goal giving recommendation on how and when to use TemplateData. The goal is not to set up rules that prohibit something as Commons may receive template imports from various Wikipediae that choose another way.
The issue with TemplateData
editBeside technical shortcomings like a poor chose of the storage (which is very limited), it suffers from the following issues:
- Mixed wikitext with JSON.
- Bots will have to take care of that (including the overhead for bot-writers to also support JSON besides Wikitext); if they don't, it's likely that they mess something up.
- An editor who never saw JSON before will easily run into trouble.
- (Not that serve because they already have to ignore some other tags): All JavaScript tools that do Wikitext-replacements and -deletions must ignore the TemplateData tag.
- Makes find & replace operations harder.
- Complicated structure of JSON and strict schema validation:
- JSON is radically different from Wikitext. It may hurt your feelings.
JSON is very strict. Forgetting to escape a double-quote ("
), making a line-break inside a string …, will render the whole JSON invalid. As a result, the page will refuse to save.
- Adding just one key that is not listed in the TemplateData-schema will throw an error and the page will refuse to save.
- No easy-to-use editors for TemplateData available:
- At least there is nothing officially supported by the Wikimedia Foundation. A standalone editor is, however, available.
- Redundancy in a different format than used before.
- TemplateData must be added separately in a different format at a different location on the same page or another page (we are also discussing where to place it).
- Counter-intuitive: JSON for documenting templates. Templates have their own syntax, which is not JSON. A very experienced coder considered the following as being possible instead of JSON he futher said, that for himself, it does not matter and that it would be even possible to add support for that (as it's easy to distinguish between one and two braces):
<templatedata> {{TD|description=Purpose |params= {{TD-par|1 |label=Meaning of 1 |description=Short description of 1 |required=1}} {{TD-par|opti |label=Meaning of opti |description={{TD-text|de|Short description of opti}} |required=0}} }} </templatedata>
Disclaimer: The initiator of this RfC is not aware of any plans by the Wikimedia Foundation to support this kind of syntax.
Advantages of raw JSON in TemplateData tags
edit- Standardised by the Wikimedia Foundation engineering department and can be copied from one wiki to another.
- Possibly better supported? seeing a major bug being open for > 14 days
- JSON is a common data-exchange format.
- And standardized mostly by international standard-setting bodies, not just WMF.
TemplateData through TemplateBox
edit- No type-mixture: Instead of inserting a new content-type, a template can be used.
- Syntax: Less error-prone compared to editing JSON (without a special editor).
- Schema: Always valid. TemplateBox always passes a structure matching the requested schema.
- Flat structure.
- Prepared for future changes. Adjustments to the LUA module can be made to support future changes. The power of control remains at Commons.
- Inserting redundant information can be avoided.
- TemplateBox is traditionally used at Commons.
- Can be easily migrated to raw JSON. All that has to be done is fetching a list of pages with TemplateData through TemplateBox enabled (this can be done, for example using a category or using this query), getting their TemplateData through the API, pretty-print it using JS-Beautifier, for example, enclose it in
<templatedata>
-tags and add it to the documentation. Conversion back to TemplateBox is not that easy.
Previous discussions
editMake the test - What are you more comfortable with?
editSample template documentation:
- Using TemplateBox:
{{TemplateBox |1 = param1 |1d-en = The English description of parameter 1. |1d-de = Die deutsche Beschreibung von parameter 1. |1type = string |1stat = required |useTemplateData = 1 |description-en = This templates serves demonstration purposes only. |description-de = Diese Vorlage dient nur zu Vorführungszwecken. }}
- Using raw JSON:
<templatedata> { "description": { "de": "Diese Vorlage dient nur zu Vorführungszwecken.", "en": "This templates serves demonstration purposes only." }, "params": { "param1": { "description": { "de": "Die deutsche Beschreibung von parameter 1.", "en": "The English description of parameter 1." }, "required": true, "type": "string" } } } </templatedata>
Where to go from here?
edit- I think that the advantages are currently at the side of using TemplateData through TemplateBox instead of putting raw JSON into Wikitext. Feel free to comment when you have time. Thank you. -- Rillke(q?) 08:43, 23 August 2013 (UTC)
Are there other Wikis using {{TemplateBox}}?
editAt Commons, 24,635 pages are documented using TemplateBox. Among those there are
- 6k templates or 3.5k excluding subtemplates like "/doc". Commons have over 125k templates or 26k templates excluding subtemplates.
- 16.5k creator templates are calling Template:Creator/documentation
- 2.8k institution templates are calling Template:Institution/documentation
Outside of Commons:
- m:Template:Tdoc (not as heavily used as here)
- d:Template:TemplateBox (not as heavily used as here)
Voting
editCommons should recommend putting raw JSON in TemplateData on templates
editor their documentation.
Oppose — JSON is overly complicated to edit at the moment. Avoids chasing users whithout these skills away. -- Rillke(q?) 08:43, 23 August 2013 (UTC)
Support JSON isn't that complicated, or at least not appreciably more so than templates themselves. Users who want to contribute to TemplateData will already need to learn a new system - the concepts of types and requiredness, e.g. - and adding another layer of complexity on top for programmers who may or may not be editors, and familiar with onwiki practices, is superfluous and wasteful. --MarkTraceur (talk) 16:12, 26 August 2013 (UTC)
- Basically it's adding
|useTemplateData = 1
to existing templateboxes and avoiding templates and other wiki markup for the English documentation. If this option passes, we need to make a plan how we want to convert existing template boxes to templatedata. One issue (in my opinion) about templatedata and, specifically it's rendered result on templates, is that even links are not parsed. -- Rillke(q?) 16:47, 26 August 2013 (UTC)
- Basically it's adding
Oppose — I personally see no reason to add TemplateData to templates if the visual editor isn't implemented. For all the things I do I keep one simple rule in my mind: KISS: if it can be simple then do it simple with as less as code as possible. The more code we add to pages the more demotivated people get when they do not get it and that already happens too much. For techies the codes are no problem, but we also have to take care of the less code experienced users. Do we want to chase them away or do we want them to participate, I go for that second option. "JSON isn't that complicated" -> that is bullshit for most users of Wikipedias, users relatively know how to work with the current templates as they are, another different layer of code doesn't help this project. Romaine (talk) 19:29, 28 August 2013 (UTC)
- First, VisualEditor isn't the only bit of software that has to handle templates. The reason I'm here discussing this is that I'm involved in Extension:UploadWizard development and I'm overseeing a project to build forms dynamically for templates that are used to describe different kinds of files ({{Information}}, {{Artwork}}, and {{Book}} most notably) - we aren't VE, and we still need TemplateData. Second, while most users of the Wikipedias (and Commons) aren't excited to understand JSON, I reiterate, template authours are not "most users". They're the elite, and they already had to learn a complex system to do what they do. Learning another, less complicated system won't be that difficult. --MarkTraceur (talk) 18:48, 4 September 2013 (UTC)
Weak support. I support attempts to standardize technical stuff across projects, and JSON seems relatively simple. It also feels rather similar to LUA (though annoyingly, it is not fully compatible). I see it as a rather good thing that it is checks for syntax errors, as the the Wikicode tolerance for them can be annoying. Many Commons templates are simple and parameter-less, and many users are able to create them. But documenting them should not be very difficult either - just as people copy-paste-edit the Wikicode from one template to the next, they can copy-paste template documentation. However, I have to admit I have not taken the time to check in detail how the extension works. For example, for example, is the description translatable ? --Zolo (talk) 07:33, 30 August 2013 (UTC)
- A glad look at the the provided examples will answer your last question. -- Rillke(q?) 08:49, 30 August 2013 (UTC)
- Oops yes sorry. Of course that requires to learn a new format, but that seems relatively intuitive to me. I like the way it avoids unwieldy parameter names like "|7stat=" that make it annoying to update the documentation of large templates. --Zolo (talk) 09:36, 30 August 2013 (UTC)
- Are you aware that
params
is a key-value construct, i.e. an object? That means that independent from your input the parameters can end up anywhere, so there is no point in sorting anything (this is defined by JSON): An object is an unordered set of name/value pairs. -- Rillke(q?) 13:24, 30 August 2013 (UTC)- That means that there is no way we can order the documentation of {{Artwork}} so that it follows the layout of the template... That is going to look confusing. --Zolo (talk) 13:52, 30 August 2013 (UTC)
- Yeah, this is just another design-issue I see with TemplateData. And I would be glad if you would play a bit with templateData and JSON and report your experience here (or the talk page). Looks easy ≠ is easy :) -- Rillke(q?) 15:16, 30 August 2013 (UTC)
- I have tested it a bit. Actually, the error messages are very unspecific, so that is not much better than Wikicode in that respect. I would think it is ok once it can be edited with the visual editor, though. That the extension does not cover all parameters of {{TemplateBox}} may also be a problem. Still, with Lua and Wikidata, templates are bound to become more complex - to the extent that it would probably make a lot of sense to centralize them- so I think we should strive to keep things as similar as possible across projects. --Zolo (talk) 07:41, 2 September 2013 (UTC)
- Export from TemplateBox to TemplateData will be quite easy. See that showcase, for example: It is a copy of Template:TemplateBox/doc, just with
|useTemplateData=export
. About editing TemplateData with VE: That would be great but I am unable to find any plans for that. Could you give me a pointer? If I do understand James (see below) correctly, he believes that a GUI editor for TemplateData is not important because only a small, experienced portion of people would edit this anyway. -- Rillke(q?) 08:36, 2 September 2013 (UTC)- I was just assuming based on the fact that it was deployed to all WMF websites and de:Hilfe:VisualEditor/TemplateData suggests that the extension was built with the visual editor in mind, but actually I have no indication that TemplateData themselves will be editable through the visual editor. --Zolo (talk) 13:46, 3 September 2013 (UTC)
- Export from TemplateBox to TemplateData will be quite easy. See that showcase, for example: It is a copy of Template:TemplateBox/doc, just with
- I have tested it a bit. Actually, the error messages are very unspecific, so that is not much better than Wikicode in that respect. I would think it is ok once it can be edited with the visual editor, though. That the extension does not cover all parameters of {{TemplateBox}} may also be a problem. Still, with Lua and Wikidata, templates are bound to become more complex - to the extent that it would probably make a lot of sense to centralize them- so I think we should strive to keep things as similar as possible across projects. --Zolo (talk) 07:41, 2 September 2013 (UTC)
- Yeah, this is just another design-issue I see with TemplateData. And I would be glad if you would play a bit with templateData and JSON and report your experience here (or the talk page). Looks easy ≠ is easy :) -- Rillke(q?) 15:16, 30 August 2013 (UTC)
- That means that there is no way we can order the documentation of {{Artwork}} so that it follows the layout of the template... That is going to look confusing. --Zolo (talk) 13:52, 30 August 2013 (UTC)
- Are you aware that
- Oops yes sorry. Of course that requires to learn a new format, but that seems relatively intuitive to me. I like the way it avoids unwieldy parameter names like "|7stat=" that make it annoying to update the documentation of large templates. --Zolo (talk) 09:36, 30 August 2013 (UTC)
- A glad look at the the provided examples will answer your last question. -- Rillke(q?) 08:49, 30 August 2013 (UTC)
Commons should recommend adding TemplateData thought TemplateBox
editSupport — Seems to be currently the best and easiest option for most users. -- Rillke(q?) 08:43, 23 August 2013 (UTC)
Oppose TemplateData isn't meant for "most users", it's not even meant for "advanced users". It's meant for template authours and programmers. Template authours are used to dealing with a complex language already - I would think that JSON would be a breath of fresh air for them - and programmers live, eat, and breathe JSON, so it makes little sense to add another layer of complexity that they don't understand. --MarkTraceur (talk) 16:12, 26 August 2013 (UTC)
- We will likely never get rid of the template-syntax… this is how MediaWiki worked for about 10 years now. -- Rillke(q?) 16:42, 26 August 2013 (UTC)
Oppose - Such recommendation was added to nl-wiki and every addition of TemplateData went wrong and had to be fixed. If we are going to recommend this, then we will let users implement it with too much errors. If it is really wanted it is better that it is implemented by experienced users. Romaine (talk) 19:32, 28 August 2013 (UTC)
Support I think it is best for now. by ReviDiscussSUL Info at 08:10, 29 August 2013 (UTC)
Support — Template authors are often average users. When possible we should avoid autocracies based on programming knowledge, rather than embrace them. Hyacinth (talk) 22:41, 29 August 2013 (UTC)
Oppose this would lead to non-standard, Commons-based-only template documentations; many other wikis will implement different TemplateBox-like templates to generate TemplateData, and one would have to learn many different syntaxes to do the same thing. TemplateData is standard, scalable, produces standard output, and is not so hard to write and read. --Ricordisamoa 23:16, 29 August 2013 (UTC)
- I see the issue and agree. Would you agree with "For new or undocumented templates, Commons recommends using JSON enclosed in TemplateData (where to place the <templatedata>-block, btw?), while for existing documentation, it is recommended to keep TemplateBox". To show how easy export is, and to prevent unfounded fears that templates documented with TemplateBox could not be exported, I've set up a showcase. This is a copy of Template:TemplateBox/doc just with
useTemplateData=export
. -- Rillke(q?) 14:45, 30 August 2013 (UTC)
- I see the issue and agree. Would you agree with "For new or undocumented templates, Commons recommends using JSON enclosed in TemplateData (where to place the <templatedata>-block, btw?), while for existing documentation, it is recommended to keep TemplateBox". To show how easy export is, and to prevent unfounded fears that templates documented with TemplateBox could not be exported, I've set up a showcase. This is a copy of Template:TemplateBox/doc just with
Support Over 3.5k templates, out of 26k, are already documented using {{TemplateBox}} (both numbers exclude subtemplates). Those tend to be the most used templates. Adding TemplateData thought TemplateBox should simplify documentation of those templates. I am especially worried about synchronization between TemplateData and TemplateBox documentations, which should have the same parameters and equivalent explanations. However I thing it is OK to allow users to disable adding TemplateData thought TemplateBox and allow them to add it manually. That is because many templates on commons are created by users copying their favorite templates from their favorite wiki. Other often seen group are users mostly active on other wikis, but not so familiar with Commons standards. Both of those groups might be more familiar with adding TemplateData directly. --Jarekt (talk) 04:57, 2 September 2013 (UTC)
Support I think here is an easier way for non-experienced users. Orchi (talk) 21:30, 4 September 2013 (UTC)
Oppose per the benefits of a solution that works the same way on all wikis. FDMS 4 22:50, 5 April 2015 (UTC)
Recommend to either put templatedata on a separate subpage /templatedata
or using TemplateBox
edit
We remain in control over where to present TemplateData and avoid mixed-content. The /templatedata
subpage could be transcluded automatically by TemplateBox or manually into the template. Other advantages of this approach:
- Custom editnotice with skeleton and information about TemplateData possible.
- Custom AbuseFilter possible (for whatever; for example for notifying the user when forgetting the
<templatedata>
tags around JSON. - Syntaxhighlight (e.g. through Extension:CodeEditor) easier to realize.
Weak support Still clear instructions (so avoiding a mess like with our license tags) and everyone can use what they are comfortable with. -- Rillke(q?) 13:40, 28 August 2013 (UTC)
- I would say
Strong oppose, but this isn't even a viable option. This would mean that, for COMMONS ONLY, developers would have to magically know to request (templatename)/templatedata instead of just (templatename) if they wanted to support the template in a form. This option cannot be allowed to move forward or it will totally defeat the purpose of TemplateData. --MarkTraceur (talk) 17:37, 28 August 2013 (UTC)
Oppose --Jarekt (talk) 04:58, 2 September 2013 (UTC)
Commons should not make any recommendation
editStrong oppose — When it comes to conflicts, and for newcomers, it's always good to say which is the preferred way to go. -- Rillke(q?) 08:43, 23 August 2013 (UTC)
Weak support Newcomers will probably not be editing templates, and allowing style differences is probably helpful in this case, given that e.g. User:Rillke seems to think that wiki editors will never be able to write errorless JSON and I think I'll never be able to write a comprehensive TemplateBox call without having three or four documentation windows open. So why not let the two styles coexist, with the preference of the template authour(s) winning the day in a conflict? --MarkTraceur (talk) 16:12, 26 August 2013 (UTC)
- I do not think that wiki editors will never be able to write errorless JSON but I think it will be a painful and steep learning process for all who do not write Software in their spare time. -- Rillke(q?) 16:38, 26 August 2013 (UTC)
Comment We should document and allow both ways to be used, although I think TemplateBox should be a preferred option. --Jarekt (talk) 05:01, 2 September 2013 (UTC)
Support: I personally haven't encountered any major conflicts about template documentation presentation yet, so letting template authors decide looks like a sensible choice. Also, {{TemplateBox}} and JSON can coexist. FDMS 4 22:50, 5 April 2015 (UTC)
Commons should support moving TemplateData to its own namespace
editBugzilla 54140 in TemplateData suggests that TemplateData should be more like other JSON constructs in MediaWiki, and be a ContentHandler object in a separate namespace. This would give it some amenities and make it easier to write an editor, for example, and it would also make the mixing problem magically disappear, and cause far fewer issues with viewing (because it's not on the same page as the TemplateBox documentation).
Support I opened this bug, and I like how the Campaign namespace has gone so far, so we should seriously consider this. --MarkTraceur (talk) 15:00, 17 September 2013 (UTC)
Yes. This allows validating-while-typing (hinting), CodeEditor activation and permission-restrictions, … and it could avoid the page-props limited-space issue. JSON could be still an issue but I am optimistic that an editor is created. -- Rillke(q?) 20:11, 17 September 2013 (UTC)
Support--Jarekt (talk) 00:09, 18 September 2013 (UTC)
Support —Dan-nl (talk) 21:17, 18 September 2013 (UTC)
Support I do not like the idea of mixing JSON (something inherently non-wikitext) in with the template code (something very much wikitext-based). Since there appears to be technical issues with moving the JSON stuff to a subpage of the template (my first preference), this seems to be a good alternative. I'd also like to address the presumption that experienced templaters are perfectly at ease with the concept of having to invest time in learning yet another technology to write and maintain (or in this case, document) templates. Not all of us are. I'm toying with the idea of learning LUA, because it addresses some of the things in templates that have irked me for years. However, this JSON stuff appears to solve a problem that I have never experienced, and it seems like something that just gets in the way of developing templates. JSON is something that is used off-wiki as well, so I'm sure that it's not something that would be a waste of time to learn, but the time spent learning it would be time that I could be working on templates, rather than learning yet another new technology. I think you are assuming that templaters are "jacks of all trades" when it comes to programming skills, but each skill only comes after investing time into learning it. By adding JSON, you are going to turn a lot of templaters (potential ones and experienced ones) away. Or, we might just choose to ignore the whole JSON thing and leave it as an exercise for others to do (like I do with translation, since I only can communicate well in English). If you leverage existing templating knowledge and skills to do the same thing, then it's something I could do myself, today. I might not enjoy it (creating the templates is the fun part, the documentation is something I do because it's the "right thing" to do), but I could start doing it immediately. —Willscrlt ( Talk | w:en | b:en | meta ) 20:29, 11 October 2013 (UTC)
Oppose: After the introduction of the new TemplateData editor, I don't see any technical benefits of having yet another namespace for this purpose, so please keep templates and their documentation together. FDMS 4 22:50, 5 April 2015 (UTC)
Comment: There is the Data namespace (eg.: Data:Templatedata/), where I’ve been putting TemplateData documentation for templates that exists on multiple Wikimedia wikis (see also: mw:WP:TNT). — ExE Boss (talk) 11:40, 19 September 2021 (UTC)
Discussion
editInstead of dozens of documentation about how to use and create TemplateData (some of them were even written by paid staff), I would have preferred a user interface. -- Rillke(q?) 08:43, 23 August 2013 (UTC)
- The staff documented something they built that was deployed on WMF wikis, that's pretty important. Building a user interface to edit a portion of a page is not particularly trivial, by contrast. Adding all of that code might have taken weeks, whereas the documentation could be written as they were building mw:Extension:TemplateData. --MarkTraceur (talk) 16:15, 26 August 2013 (UTC)
- I was more concerned about all the translation work done by paid stuff. Usually, MediaWiki messages translated for free by volunteers at translatewiki but since VE was pushed and the product manager was unable to recognize that more time is required, someone had to explain how this JSON-driven extension works to the majority of people. I just find that this translation time should have better spent by a developer writing an UI. If something needs a lot of documentation, it is probably not suitable for the majority of people. -- Rillke(q?) 16:35, 26 August 2013 (UTC)
- Rilke, if you're going to complain about my actions, at least have the courtesy to ping me. :-(
- As Product Manager, I felt that it was important for all the different parts of the VisualEditor ecosystem to have good documentation, and for this documentation to be available for translation as much as possible. I'm sorry that you think that WMF shouldn't document its code that it provides our communities - however, I believe this to be good practice, and something we should always try to do.
- mw:Help:TemplateData is one of several pages about VisualEditor that were created. We asked Jan and the other community liaisons to work with the community to translate into as many languages as possible the documentation, starting with a full "official" set of documentation in the core languages of English, French, German and Spanish, so that as many people as possible could easily translate it, rather than assuming that everyone is fluent in English. This is especially important right now, because VisualEditor, TemplateData and other things are changing quite a bit, and it would be rude to keep making work, adding the burden for volunteers as we improve the everyone when we can help out.
- I'd also note that there is a visual TemplateData editor developed, primarily by Moriel (one of our GSoC students), which is in testing on the Hebrew Wikipedia. Had you asked, we would have been delighted to give you some pointers, but feel free to not ask, but instead complain on here and not help us make things better. :-( Jdforrester (WMF) (talk) 18:55, 26 August 2013 (UTC)
- Hi James/ Dear Mr. Forrester, admittedly I did not search who the product manager is. It is nice, no, great, to learn that you are open for discussion and provide insights into the development process. Given the past experience with staff at bugzilla and enquiries in IRC or via e-Mail, that is great news.
- Nonetheless, I still do not understand is why one would publish VisualEditor among other tools relying on TemplateData, while a graphical user interface (UI) for editing TemplateData is not yet developed and therefore a complex documentation is required, which has to be read by everyone wanting to document templates that should be usable in these products. In this regard, I do think the deployment of all this was overly hasty. some of the largest Wikipediae also thought so
- Finally, it would be nice having something at mw:Extension:TemplateData about its future development. Will there be issues with the storage of TemplateData? How much multilingual text is it actually capable handling? Can we rely on it? Will it be properly supported? Will there be a major revamping in the near future?
- Looking forward to hear from you. Kind regards -- Rillke(q?) 22:59, 26 August 2013 (UTC)
- Templates, and especially the kinds of templates that are worth documenting, are only really edited by very experienced users. They use ridiculously-complex syntax and are prone to breaking unexpectedly. Visual editing tools for marginal tools isn't a high priority for us, sorry, and I disagree that we should have spent donor funds on it when TemplateData was released in April (and yes, it would have been great if people started to use it when we released it, not some months later when VisualEditor started using it).
- I agree, talking about the future development of TemplateData at mw:Extension:TemplateData would make sense. However, right now there's not really something to say for sure - questions like you ask are great, and you should have asked them before. :-) The best venue would be mw:Extension talk:TemplateData. I'm not sure why you think derailing Commons to adopt mis-usage of TemplateData that makes it useless is a good idea, though.
- Jdforrester (WMF) (talk) 18:00, 28 August 2013 (UTC)
- are only really edited by very experienced users -- Sorry, but I disagree. As Commons is a multilingual wiki; I think translators of template documentation have a right not being forced to learn how to use JSON. -- Rillke(q?) 18:18, 28 August 2013 (UTC)
- Has TemplateData been user-tested? Also, I do not see why it should be "mis-usage" offering a different interface for users to insert TemplateData. -- Rillke(q?) 19:25, 28 August 2013 (UTC)
- Why does mr. forrrester have anything to do with my great great grandfathers information I know a forester personally and he is very scandolas if you have any questions contact Ashley dukellis at 3609270529 Adukellis (talk) 12:26, 24 March 2023 (UTC)
Comment Let’s not make this a WMF Vs. Community / staff vs. volunteers / whatever thing, shall we? >_>
That being said, personally the first thing that struck me when I heard about TemplateData was “Aren’t we already doing that on Commons? I have spent years documenting every parameter on each template I created using {{TemplateBox}} − do I really have to do it all over again?” So when Rillke posted on the VP that he was looking into leveraging TemplateData from TemplateBox, that just sounded perfect to me. Jean-Fred (talk) 23:34, 26 August 2013 (UTC)
- To some extent that makes sense - but if somebody is willing and excited to build documentation with the new format, it seems a mite silly to require that they learn yet another template call. I don't understand Commons templates without some pretty heavy exploration and documentation, but I've worked with TD and JSON before - same with User:Rasel160, who also needs to implement TemplateData documentation on several templates in the course of his summer project. Mostly I'm concerned with the stringent requirements that will likely come down harder on programmers who don't necessarily have a voice here on-project, and even if they do, might not see User:Rillke's policy before trying to integrate TemplateData into various templates - only to get surprised by totally different and unfamiliar requirements when an experienced Commonist comes along. If anything, I'm worried about developer vs. editor, nothing else, and having a big policy discussion, potentially resulting in an editor-focused policy that insulates a developer-focused feature, seems like the very thing to ensure that :( --MarkTraceur (talk) 23:54, 26 August 2013 (UTC)
- "Rillke's policy", :-/ -- this is how it was done for year on Commons. And of course you are welcome to voice in here, as well as other developers. That's why we have the RfC process. Also, it is not aimed to create a "stringent policy". Perhaps it should be amended to focus on existing template documentation, leaving aside new documentation, but this would require a plan: How should our documentation page actually look like? How can we integrate TemplateData into that scheme? -- Rillke(q?) 00:08, 27 August 2013 (UTC)
- "It" being template documentation, maybe, but TemplateData didn't exist a year ago, so the portion of the policy that deals with TemplateData is brand new, and AFAICT, written unilaterally. And my point isn't that developers aren't allowed to chime in - they're just not going to because either they aren't active or they aren't even on this site yet. I don't see any complication to including TemplateData in the template documentation - I did it quite successfully with {{Information}} before the policy was enacted, and others can do it with other templates after. --MarkTraceur (talk) 00:25, 27 August 2013 (UTC)
- There should be a recommendation where to place TemplateData, at least. With TemplateBox, we can even decide to hide the table generated by TemplateData or move it around, if we want to. For all interested, this is what Mark suggested instead of the current version. -- Rillke(q?) 00:45, 27 August 2013 (UTC)
- If you want to suggest a place for the TemplateData block, you could probably suggest putting a <div style="display:none"> around it if you're concerned about the table showing up, but I'd also suggest that the templates likely to be edited by programmers preferring JSON to templates may not have existing documentation, at which point it's better to keep the table around than screw around adding TemplateBox on top of it. --MarkTraceur (talk) 00:54, 27 August 2013 (UTC)
- <div style="display:none"> -- let's put another non-semantic node around this. -- Rillke(q?) 17:53, 28 August 2013 (UTC)
Comment Given that this conversation is between very few people, that Rillke and I can't come to any agreement about it, and that nobody else seems to be joining the conversation, I'd suggest giving this a week or two and, if nothing else happens, just close the RfC and rewrite the TemplateData policy page to be descriptive of multiple methods of including TemplateData (raw TD blocks, TB calls, mixed) instead of prescribing a particular method that may or may not work best for various templates. --MarkTraceur (talk) 17:46, 28 August 2013 (UTC)
- I just did not announce it yet, to give us time to think about it before we steal the time of other users. I am sure Jarekt will also comment here, after he is back. -- Rillke(q?) 17:53, 28 August 2013 (UTC)
- Instructions amended. Unsurprisingly, that makes me sad; the whole way TemplateData was developed does: We cannot properly query it with LUA, so we cannot build copy&paste templates and all the other features of TemplateBox will be gone, once it is established. -- Rillke(q?) 09:14, 2 September 2013 (UTC)
Comment: So, in order for VE not to make a mess of templates one more thing is going to be pushed down our throats, after VE itself. M’kay… And, so, what’s the course of action to make this the worst possible and delay the most the implementation of VE? I’ll vote for anything that will hurt VE, on this page and on any page. Thanks to all who wrote the above, too, including VE supporters, for making it really clear what are the problems with TemplateData, and what are its “advantages”! Also: Who ever says that complex templates «are only really edited by very experienced users» is an arrogant elitist drone who doesn’t deserve the previledge of being hired by a user driven community. (Try Redmond, I heard they are still hiring; or Mountain View, too, sadly so.) -- Tuválkin ✉ 20:40, 28 August 2013 (UTC)
- I do not think your comment is very helpful − I do not believe it reflects any truth about TemplateData nor how the Commons community should deal with it. I find your comment uselessly aggressive, bordering personal attacks. Please assume good faith. Please do not bring any antiVE crusade here − this is not the point of this RFC. Thanks. Jean-Fred (talk) 09:31, 29 August 2013 (UTC)
- I will second Jean-Fred's sentiment. --Jarekt (talk) 05:06, 2 September 2013 (UTC)
Comment I regret this conversation seems to have escalated so quickly and that proponents of both solutions act very defensively.
I believe the very assertive vocabulary (“discouraged”) in the original policy was unfortunate, and it seems it heavily polarised the conversation. As I said above, leveraging on {{TemplateBox}} looks like an obvious win to me, and I would appreciate if “TemplateBox detractors” would consider this opinion, as I happen to have created, edited and documented several hundreds of templates in my service of the Wikimedia Commons community − checking my edit counter, it appears I created more than 200 documentation subpages using {{TemplateBox}}. I am not saying the VE team did a bad job with TemplateData (I cannot really judge that anyway) ; I am saying that I would appreciate if “TemplateBox detractors” would consider how the Wikimedia Commons community (which is no small community in any way, last time I checked) has dealt for years with template documentation. Finally, I think TemplateData is a means to an end − a better VE experience − and frankly, if I do care about and want a better VE experience on Wikimedia Commons, I don’t really care about the syntax on how it is achieved. Jean-Fred (talk) 09:31, 29 August 2013 (UTC)
- Well, something is moving-on. I assume, we find a solution that satisfies all needs. I am still not happy about the idea using JSON for documenting templates (the whole idea sounds awkward). In the discussion at de.wikipedia, someone assumed it was done that way because it was easier to force people learning a new syntax instead of writing a parser. I share this opinion. -- Rillke(q?) 15:13, 30 August 2013 (UTC)
Comment
pov: a developer working on a MediaWiki extension for Commons that uses several templates, such as, Artwork, Book, and Photograph. one of the main goals of the extension is to be able to match metadata coming from an external source to the parameters in a template.
a bit of context: when we started to develop this extension, the quickest way to move forward was to hard code the template parameters based on those within the TemplateBox documentation. we agreed that this was less than ideal, but we didn’t have the resources to focus on developing the functionality that would dynamically parse the TemplateBox and output the parameters in a more useable format, such as JSON. i believe it was in June 2013 that i first heard of TemplateData. what i understood at that time was that it would produce a JSON output describing the parameters within the template — that sounded exactly like what we wanted.
at present: i have been exploring the actual implementation over the past week and from my pov, this API call, is definitely what i was hoping for. i'm not directly concerned with how this JSON is produced — via a <templatedata> tag or via a parsing of the {{TemplateBox}}; i just need a way to retrieve those parameters in a more program friendly format.
“my struggle”: during the past week i have been trying to get my local developer environment and the test website on Wikitech to work properly with the TemplateBox implementation of TemplateData. the main hurdle, i found, was the set-up of Scribunto. for whatever reason the TemplateBox implementation of TemplateData required the sandbox version of lua rather than the standalone version — i still feel this needs to be resolved, but for now, i can move forward with my development. also, i couldn’t find any documentation that told me, as a developer, how to configure my local development or test server for implementing the TemplateBox/TemplateData solution. i did find this article, which helped, but i found some aspects missing, which i added. hopefully that will help other developers with the implementation.
Template data section in the documentation: i find the two tables confusing; i would prefer to see one table with all of the information in it.
<templatedata> vs {{TemplateBox}}: i personally prefer JSON. from what i understand thus far, the main question is how to implement TemplateData in the templates:
- use <templatedata> and depreciate {{TemplateBox}}
- allow either method
- continue with {{TemplateBox}} only
- store the <templatedata> elsewhere, maybe on a ContentHandler page
- continue to support the API call in order to retrieve the JSON representation of the template parameters
- nr 1 seems like a major change that would need a wide consensus before implementing.
- nr 2 seems like it would be a transition process, would need wide consensus before implementing, and would be confusing at first.
- which method do i use?
- should i replace one with the other?
- which one is preferred?
- nr 3 seems like the “common sense” solution to me; as mentioned above:
- wikitext is the “defacto” template language
- a lot of effort has been put into creating and maintaining current {{TemplateBox}} implementations
- having both wikitext and JSON in the template will be confusing
technical architecture: i did a quick search, but i couldn’t find any documentation that describes the architecture. are there pages that describe:
- the TemplateData architecture
- discussion on the “best” implementation
- consensus building on the use of <templatedata> vs {{TemplateBox}} in the templates
Closing this RfC
edit@Rillke, MarkTraceur, Jdforrester (WMF), Jean-Frédéric, and Romaine: @Tuvalkin, Hym411, Hyacinth, Ricordisamoa, and Zolo: @Jarekt, Orchi, Dan-nl, and Willscrlt: If still relevant, I would like to close this RfC with this conclusion:
- Consensus reached on the option "Commons should support moving TemplateData to its own namespace"
Any final comment? --Micru (talk) 12:34, 8 March 2014 (UTC)
- There is consensus but it's neither implemented nor implementable by the community and therefore, for now, not applicable. Thus, closing and applying this consensus is not possible, yet. IMHO, this could stay open until we have the opportunity to move template data to a dedicated namespace. Usually more people start to comment when something is going to happen. -- Rillke(q?) 12:52, 8 March 2014 (UTC)
- IBTD, there is no clear consensus. Tdoc (a simplified TemplateBox as of 2010) and TemplateBox are horrible, and together with all those poorly documented + edit protected translation horrors excessively hostile to contributors. Folks will try to figure out where this stuff throws template tracking "parameter redefinition" errors for years, while mw:Help:TemplateData without i18n is trivial, even the "manage template data" wizard tends to get it right, and can be easily overruled. –Be..anyone (talk) 13:12, 2 January 2015 (UTC)
- Template data wizard hasn't been available at the time of this RfC. -- Rillke(q?) 18:50, 2 January 2015 (UTC)
- Quote Template:TemplateDataInfo/i18n: There is an ongoing discussion about that matter. Feel invited to comment if you are experienced in either way, your time permits and if you like to share your opinion or to make a suggestion. I like to share my opinion that everybody involved remotely in the creation of Template:Multilingual description or anything shown on Template:LangSwitch/doc not contained in Template:LangSwitch/doc, where I don't find the source in more than one hour, shall be indefinitely banned from this project. –Be..anyone (talk) 19:22, 6 January 2015 (UTC)
- What exactly can't you find? -- Rillke(q?) 21:42, 6 January 2015 (UTC)
- And why this and the following changes? because this template has to work as is, get rid of HTML table while at it -- What does template has to work as is mean and how is this related to this RfC? -- Rillke(q?) 21:49, 6 January 2015 (UTC)
- Quote Template:TemplateDataInfo/i18n: There is an ongoing discussion about that matter. Feel invited to comment if you are experienced in either way, your time permits and if you like to share your opinion or to make a suggestion. I like to share my opinion that everybody involved remotely in the creation of Template:Multilingual description or anything shown on Template:LangSwitch/doc not contained in Template:LangSwitch/doc, where I don't find the source in more than one hour, shall be indefinitely banned from this project. –Be..anyone (talk) 19:22, 6 January 2015 (UTC)
- Template data wizard hasn't been available at the time of this RfC. -- Rillke(q?) 18:50, 2 January 2015 (UTC)
Transcoding bugs
editThere are bugs in transcoding actual templates, such as {{Tl}}, whereby expanded (raw) HTML code meant for browsers gets shown in the TemplateData table. See, for example, the documentation area of {{Information}}, where {{tl|sometemplatename}} gets expanded into HTML/XHTML code instead of displaying as {{sometemplatename}}. -Mardus /talk 12:29, 12 December 2018 (UTC)