Wiktionary:Votes/2017-06/Requests for documentation

Voting on:

Creating a new request page, as per the specifications below.

• Request page name:

  Wiktionary:Requests for documentation (WT:RFDOC)

• Tagging template name:

  {{rfdoc}}

• Purpose:

  Handling requests to create documentations of templates and modules, and fix the documentations that are incomplete, superseded, and/or wrong.

• Request page appearance/layout:

  Generally, the same as WT:RFV, WT:RFD, WT:RFDO, WT:RFC and WT:RFM.

• How to create and deal with requests:

  Generally, the same way as in the other request pages mentioned. Discussions are to be archived at the talk pages of the affected templates and modules as usual.

• Rationale:

  Category:Templates and modules needing documentation contains 3,429 members as of July 1, 2017. Where to start? And these are only the missing documentations. That category does not contain the incomplete, superseded, and/or wrong documentations. By creating requests, we would be able to see which documentations we would like to create or fix first, and we would have the chance to discuss them and close the requests only when they are done.

Schedule:

• Vote starts: 00:00, 8 July 2017 (UTC)
• Vote ends: 23:59, 6 August 2017 (UTC)
• Vote created: --Daniel Carrero (talk) 10:47, 1 July 2017 (UTC)

Discussion:

• Wiktionary:Tea room/2017/June#"the Variety -er"
• Wiktionary talk:Votes/2017-06/Requests for documentation

1. Support. See also the talk page for a discussion concerning whether this needs to be voted. --Daniel Carrero (talk) 01:39, 8 July 2017 (UTC)

   I find it interesting that some people below who opposed the existence of this vote said or seemed to imply that WT:RFDOC can simply be created without a vote. I guess I really will try to be extra sure in the future about whether a vote is needed and think twice about creating votes for some things rather than just doing them without a vote. Still, there are a few some controversies and oppose votes (still in the minority, but the vote has not ended yet) so I think at least the vote was not a total waste of time. I mean, nobody can claim something like "WT:RFDOC could just be created without a vote because it's 100% noncontroversial!"

   I like to propose implementing big projects on Wiktionary, so part of me would almost like to say "Oh, turns out I can do some big things without a vote, thank you!" But I'd rather see comments like "the vote was not needed" because it means maybe I went too far to get consensus; it's better than risking doing things without consensus. If I just created the page without a vote, someone could still complain and ask "where's the consensus?" No one replied in the BP discussion about the vote (link). --Daniel Carrero (talk) 19:12, 25 July 2017 (UTC)

2. Support just in case anyone thinks this does in fact require a vote (I would third that this can be simply created without further discussion). --Tropylium (talk) 19:21, 8 July 2017 (UTC)
3. Support the creation of the page, but oppose this vote, as it is contrary to the fundamental philosophy of "being bold". A simple beer parlour discussion would have been enough. This, that and the other (talk) 10:29, 9 July 2017 (UTC)

   Support since I would use it. Germyb (talk) 21:25, 9 July 2017 (UTC)

4. Support creating the page, but oppose the creation of this vote per above. You're a little too vote-happy sometimes Daniel. It's good to have consensus, but don't be afraid to make changes that don't require a vote. Just announce it in Beer Parlour, wait a bit, and if no one responds, then there's probably no one who opposes the idea enough to say so. Andrew Sheedy (talk) 23:15, 9 July 2017 (UTC)
5. Support --Barytonesis (talk) 21:43, 10 July 2017 (UTC)

   @Daniel Carrero: also, do you think it would be possible/useful to categorise documentation pages by language? --Barytonesis (talk) 18:13, 12 July 2017 (UTC)

   Yes, whenever possible. Suggested category name: Category:Requests for documentation concerning English or Category:Requests for documentation of English templates and modules. --Daniel Carrero (talk) 18:25, 12 July 2017 (UTC)

6. Support — Vorziblix (talk · contribs) 13:37, 12 July 2017 (UTC)
7. Support — SGconlaw (talk) 16:55, 12 July 2017 (UTC)
8. Support -Xbony2 (talk) 00:30, 15 July 2017 (UTC)
9. Support – though, as mentioned above, this could be done without a vote. — Eru·tuon 20:20, 23 July 2017 (UTC)

   Regarding the statement that we don't need any "requests for documentation" because we have Category:Templates and modules needing documentation: First, some templates aren't even in that category because they don't have the {{documentation}} template transcluded. Second, many templates without documentation are hardly used or are even deprecated, or for some reason don't need documentation. (For instance, do we urgently need documentation for {{nominative plural of}}?)

   The purpose of "requests for documentation" is to find templates that someone actually is using, or wants to use, and doesn't know how because there's no explanation. I'm sort of skeptical that we need a dedicated request page (maybe people could just post in the Grease Pit or one of the other discussion pages) and it seems like extra clutter, but maybe there will be enough posts to warrant it. — Eru·tuon 18:48, 25 July 2017 (UTC)

   @Erutuon: I think automatically adding things to a needing category is a bad idea since it leads to an overflood and nothing useful. This is why I thing a category containing requests in the name, to be exclusively filled manually, would be a good solution. A whole lot of "needing" categories were recently renamed to "request" via Wiktionary:Votes/2017-03/Request categories 2, a good thing; and they are really request categories, largely filled by manually inserted requests such as {{rfp}}. --Dan Polansky (talk) 08:50, 30 July 2017 (UTC)

   @Dan Polansky: I see the value of the request category to which entries are added manually (if my comment above suggested I didn't), but think that documentation pages should still be automatically added to a general "documentation missing" category by default (it could use retitling). Admittedly, the process of adding the category doesn't actually capture all templates without documentation: only if someone has added {{documentation}} to the template page and there is no documentation page, or has created the documentation page using the "create it" link from {{documentation}} (which loads {{documentation/preloadTemplate}}, which adds {{documentation needed}} to the page) and hasn't removed that template. But anyway, it seems more organized to have some kind of category for templates missing documentation, even if it isn't a particularly good way to find the templates for which writing documentation would be useful to other editors. — Eru·tuon 22:12, 30 July 2017 (UTC)

1. Oppose Dan Polansky (talk). Requests for documentation are requests to add something, while RFD, RFDO and RFV are requests leading to removal; one could quibble about RFV since it is nominally a request for adding attesting quotations, but RFV is nonetheless a process often leading to removal. There are already too many request pages, IMHO. I consider the existence of RFC not so fortunate. I feel we urgently need something like RFV and RFD as separate process pages, while I do not see this urgent need for missing template and module documentations. I don't quite understand how the request page is supposed to do something that Category:Templates and modules needing documentation does not do; are people placing items to the category at a whim? If so, could not we have a request category for them rather than the unfortunate needing? --Dan Polansky (talk) 12:47, 23 July 2017 (UTC)

   To answer your "...at a whim?" question: Category:Templates and modules needing documentation is filled automatically with two things: 1) all modules without a documentation; 2) all templates without a documentation (technically, only the templates that have {{documentation}} and are without a documentation, but apparently there's an unspoken rule that all or most templates need to have {{documentation}}). Therefore, it's comparable to a category for "all entries without etymologies" or "all entries without quotations" as opposed to actual "requests".

   If we just created a new "request" category without a request page (possibly populated by a template like {{rfdoc}}, which is part of this vote), maybe there's some risk that some people would be going to use it at a whim in many templates too, since they are already supposed to add {{documentation}} everywhere. The request template could be named {{documentation urgently needed}} or something, but that could be easily added at a whim in many entries too. Having WT:RFDOC would give the chance for people to tell us exactly why the request was made and how to solve it.

   I think having WT:RFDOC would be a good idea, for the purpose of discussing whether a documentation has reached certain standard in documentation. Just placing templates and modules in a category does not indicate what are the problems with them. Category:Templates and modules needing documentation tells us that the documentations don't exist, but other documentations may be incomplete, superseded, and/or wrong in ways that need to be discussed somewhere. --Daniel Carrero (talk) 16:43, 23 July 2017 (UTC)

   Thank you for an explanation. Automatically filled Category:Templates and modules needing documentation is useless as nearly everyone can see, and I am grateful to you for having created a vote to rename the misnamed "needing" categories to "request". Request categories are for manually and selectively inserted requests, not for insertions at a whim, even though this is a fight that I am still fighting when someone starts adding {{rfp}} whereever pronunciation is missing only because "it is missing". The selective approach was confirmed for RFE in Wiktionary:Votes/2014-12/Adding RFEs to all lemma entries where etymology is missing and could be similarly confirmed in a broader vote. --Dan Polansky (talk) 09:02, 30 July 2017 (UTC)

   I'm happy I could help by creating the vote to rename the misnamed "needing" categories to "request". You're welcome. --Daniel Carrero (talk) 12:01, 30 July 2017 (UTC)

2. Oppose. Seems like extra bureaucracy and more maintenance required with little benefit. I think a new template and a new category to go with it should be sufficient. The template can have a parameter that allows editors to explain why they've added it, like we have with Template:attention. @Daniel Carrero you say above that WT:RFDOC "would be a good idea, for the purpose of discussing whether a documentation has reached certain standard in documentation." Are those discussions really needed in very many cases? (By the way, I agree with those above who say this could have been done simply with a beer parlour discussion rather than a vote.) —Granger (talk · contribs) 23:50, 23 July 2017 (UTC)

   Yes, probably. How many is very many? Category:Templates and modules needing documentation has 3,440 templates and modules. --Daniel Carrero (talk) 08:49, 24 July 2017 (UTC)

   I understand that, but I asked whether discussions are really needed in very many cases. I would imagine that in most cases, the documentation could simply be added without a discussion. Is a discussion really needed for many of them? —Granger (talk · contribs) 10:50, 24 July 2017 (UTC)

   That is a good point. I'm not sure about "in most cases", but I agree about this: there are probably some, or even many cases where the documentation could simply be added without a discussion. --Daniel Carrero (talk) 10:54, 24 July 2017 (UTC)

   How is this "bureaucracy" or "maintenance"? There's no obligation to start a RFDOC discussion under any conditions: anyone who wants to document something can just go ahead with it. The page would be to specifically request documentation when someone doesn't understand a template, or thinks other users might not: it makes a more visible central place than the individual template talk pages. (Similarly, it's not as if the existence of the Tea Room somehow prevents anyone from improving some given entry if they so wish.)

   There could be maintenance implications if at some point someone wants to start a "templates with unclosed RFDOC discussion" category beside the main templates needing documentation category, but that's a separate issue (which I would not support).--Tropylium (talk) 03:10, 26 July 2017 (UTC)

   RFV and RFD do require maintenance, in the form of closing and archiving discussions as well as adding new month headers. It is extra bureaucracy because in addition to simply fixing the documentation, users would need to comment in the discussion and close it as well. Creating a new request page would also add clutter and increase the amount of mental energy needed to understand and navigate Wiktionary's internal bureaucracy. I don't see why we should waste editors' time with all of that when a new template and category would basically accomplish what is desired as far I can tell. —Granger (talk · contribs) 11:29, 26 July 2017 (UTC)

   OK yes, that's coherent, though this still seems to transfer point-for-point also as an argument in favor of deleting the Tea Room. Partly even as an argument against talk pages in general (if someone asks someone else to do something, it is an identical degree of "extra maintenance" to have to reply to them that the thing has been done). --Tropylium (talk) 12:50, 26 July 2017 (UTC)

   Indeed, WT:Tea room's setup being similar to RFV, full with closing discussions, putting {{rft}} templates into mainspace, and archiving, is odd, and could be abandoned. Nonetheless, Tea room could still exists, and be set-up like Beer parlour. --Dan Polansky (talk) 09:10, 30 July 2017 (UTC)

3. Oppose If someone wants to spend their time creating documentation they can look in the request category. I don't want to create another request page. DTLHS (talk) 23:54, 23 July 2017 (UTC)
4. Oppose, only because this can and should have been done without a vote. My opposition to this vote should not be read as opposition to the creation of a "requests for documentation" page. --WikiTiki89 18:23, 25 July 2017 (UTC)

   This is a good vote to have. It gives people the opportunity to oppose the proposal and explain why. --Dan Polansky (talk) 08:44, 30 July 2017 (UTC)

   That could have been done in a BP discussion. Or in an RFDO discussion after such a page was created. --WikiTiki89 18:01, 31 July 2017 (UTC)

   @Wikitiki89: In a vote, this is much easier to notice than in Beer parlour. It is courteous of the creator of the vote to go via vote when he could have instead have forced the thing upon the project with very little discussion, or discussion that very few people noticed. And RFDO is even harder to notice. --Dan Polansky (talk) 11:58, 5 August 2017 (UTC)

   Some things like this one do not need consensus to be done. If there is one editor who would find it useful and wants to put in the time to set it up, he can go ahead and do so. If afterwards, other editors don't like it and want to delete the page, they are the ones who would need to demonstrate that there is a consensus to do so. Anyone who cares about a page's existence should contribute to its RFDO discussion (and that is why we put a box at the top of pages that are in RFDO). --WikiTiki89 15:33, 7 August 2017 (UTC)

5. Oppose A vote undertaken for something that doesn't require a vote is an abuse of the process. Among the evils is that we rarely foresee the consequences of any such vote. Also does this create some kind of precedent that creating similar pages would require a vote? In general the more words we have in policies, the more potential for lawyering, inherently and absolutely evil in this kind of organization. We should restrict votes to the matters that truly require them. DCDuring (talk) 23:56, 6 August 2017 (UTC)

1. Abstain Yet another bureaucratic page is not what I wanted to come out of my comment about how our documentation is inadequate. Perhaps we could have a rule like "never create anything unless you document it"; but basically people aren't gonna write docs unless they want to, and I think this proposed page would just create way more heat than light. Equinox ◑ 22:16, 23 July 2017 (UTC)

   Well, I for one am likely to respond to requests for documentation, even when the template or module wasn't created by me. — Eru·tuon 21:36, 25 July 2017 (UTC)

2. Abstain Per above. --Victar (talk) 19:39, 25 July 2017 (UTC)
3. Abstain A template that adds pages to a request category might be sufficient. Germyb (talk) 20:05, 29 July 2017 (UTC)

Result: unclear.

The simple vote count, without taking voters' comments into consideration, would be as follows.

• no consensus: 9-5-3 (64.28%).

But @Wikitiki89 voted oppose while saying "My opposition to this vote should not be read as opposition to the creation of a 'requests for documentation' page." So not an actual oppose? This would cause the vote result to be as follows.

• passed: 9-4-3 (69.23%)

When closing previous votes, I've been taking the actual vote comments into consideration, not just the simple "support/oppose/abstain" count.

I'm not sure what to do. --Daniel Carrero (talk) 00:43, 7 August 2017 (UTC)

That sounds to me like there is consensus that someone can make this page if he wants, but there is not the weight of a vote behind it, so that people would feel more free to change how it works or remove it in the future if they sense consensus from the beer parlour. Germyb (talk) 01:40, 7 August 2017 (UTC)

I think an explicit oppose vote has to be counted as an oppose vote. It sounds to me like Wikitiki89 is saying he doesn't mind the idea of an RFDOC page, but doesn't want to do it through a vote. If I were you, I might start a BP discussion and see if you can get consensus there, as several users (including me) commented that they thought a BP discussion instead of a vote would be appropriate. —Granger (talk · contribs) 10:38, 7 August 2017 (UTC)

I opposed. You can't just discount my vote. However, my position is that this page can nonetheless be created, despite the failure of this vote. If I didn't want my vote to be counted, I would have abstained. --WikiTiki89 15:30, 7 August 2017 (UTC)

@Wikitiki89, Mx. Granger, Germyb: Personally, I think the creation of a new request page should pass a vote first. I'm aware that not everyone agrees with me, but I stand by my position. I accept that the result is "no consensus", that seems right, but because of the vote result I'm not interested in creating that page right now. That's just me. Other people might want to create it, if they think the vote was not needed in the first place. I wanted to create the page, but creating it right now wouldn't feel right to me. If I created it today, it would feel like I'm ignoring the oppose votes to do it. If nobody creates it, I plan on proposing the creation of this page again on the Beer Parlour in maybe one or two years at least. --Daniel Carrero (talk) 06:24, 12 August 2017 (UTC)