Forum:Amending the Template Policy
TemplateData serves more than one purpose. First it serves as a thorough documentation on all the parameters that a template uses. It also aids the visual editor, so that users can fill in values in infoboxes and such and be sure to get it right. It can be a bit tricky to get the JSON right, but that's nothing a JSON validator can't handle. Which brings me to what I'm proposing as changes to the Template Policy (RS:TPOL).
- Recommend a style guide template for the template documentation. Having all the documentation pages follow a similar structure is good. I'm proposing starting with a general description followed by general usage, then examples and other paragraphs and for last templatedata which also documents the parameters. (I realise not every documentation page will lend itself nicely to fit that style, but that's fine)
- Recommend templatedata over manually documenting the parameters. Nothing wrong with being oldschool, but the former is better. More importantly documentation should never have both (I've seen several cases of this).
Separate from the policy changes I'm also suggesting that the TemplateData template ought to be nuked or at least have its default set to not collapsed. The reason for that is that parameter documentation is essential documentation and as such should not be hidden. Having the style guide specify that TemplateData has to be at the bottom of template documentation pages should be enough to keep it out of the initial view of the contributor. It's also good that it's visible in case there are errors in it, that way there is a bigger chance people will fix them. Ironically enough that same template mentions the importance of keeping templatedata correct and current. --The scribe 07:18, 4 July 2020 (UTC)
Technical concern - Our pattern for multi-version infoboxes (see Template:Standard infobox parameters) seems to be incompatible with TemplateData. Any parameter in switchfoboxes can be provided as the default (e.g.
|astab = 3), or it could have multiple values specified with numbers in the param names (
|astab1 = 3,
|astab2 = 0).
This ends up being a problem for the Visual editor. If we define a parameter
astab in TemplateData, the visual editor doesn't identify
astab2 under the same name, so the params with numbers show up out of order at the bottom. Supposing
astab is a required parameter, Visedit will incorrectly consider it to be missing, and will automatically add
|astab= to the template when it's modified. To avoid this we could mark all parameters as optional, but this is semantically misleading. It's also infeasible to list every legal infobox parameter including numbers, since there are so many possible (e.g. Infobox Monster has more than 600 distinct parameters in use). I would rather not introduce this confusion (or maintenance burden) in the visual editor.
For any template where it's feasible to list out all the possible parameters (any templates that don't use switchfo), I support the proposal and would prefer using TemplateData instead of a regular list. Riblet15 (talk) 07:55, 4 July 2020 (UTC)
Mixed - TemplateData is great for visedit, but I've always found it much more annoying to read as an editor. I don't see why we can't support both, and we don't necessarily have to require editors to write both types of documentation when they create a template, as someone else can come in and do the other one later. Agree with Riblet's concern regarding numbered params becoming a nightmare. -Towelcat (talk) 02:48, 16 July 2020 (UTC)
Comment - I think we should add a style guide for documentation and have consistent docs, or at least as consistent as we can get them given the obvious differences in templates. My preference would be having a general description, followed by a block with usage such as on Template:CostLine/doc#Usage, then an empty example for copy pasting, then a classless table for params like on Template:CostLine/doc#CostTableHead, then usages of the different important params, then TemplateData collapsed at the bottom.
With regards to your 2nd and last points, I think TemplateData is a necessary evil for the other necessary evil that is the Visual Editor, but in my opinion it's useless for actually having readable and useful documentation for editors. We should always have both so long as we have the Visual Editor.08:38, 24 July 2020 (UTC)
- Naked tables (no styling) is definitely a lot better than using headers and paragraphs, which also clogs up the TOC, and is arguably just as bad looking as templatedata. On a related note, perhaps we should change the site's stylesheets to remove style from templatedata tables too? I'd be opposed to try to force any editor to duplicate parameter documentation, that would have to be voluntary. --The scribe 20:58, 24 July 2020 (UTC)