Wikipedia:Wikipedia Signpost/Templates/Voter/Documentation

Setting up a poll

This template is a proposal for an in-wiki polling apparatus for weekly use by the Signpost. The parameters are as follows:

{{Wikipedia:Wikipedia Signpost/Templates/Voter
| image = <!-- An image for the top-right corner of the sidebar; defaults to the Signpost logo. -->
| question = <!-- Title of the poll. -->
| option_one = <!-- Name of the first option, as reported in the legend and in the vote button. Defaults to the test poll. -->
| option_one_color = <!-- Color of the first option choice; defaults to #006699, Foundation blue. -->
| option_one_vote_collection_page = <!-- Where the votes for option one will be collected. Defaults to the test poll. -->
| option_two = <!-- Name of the second option, as reported in the legend and in the vote button. Defaults to the test poll. -->
| option_two_color = <!-- Color of the first option choice; defaults to #339966, Foundation green. -->
| option_two_vote_collection_page = <!-- Where the votes for option two will be collected. Defaults to the test poll. -->
| min_votes = <!-- The minimum number of votes that must accrue before the template begins to display results. Defaults to 10. -->
| break = <!-- If this parameter is non-empty the votebar is split into two to better accommodate lengthier poll options. -->
}}

Setting up a poll requires at least two additional pages be created: one for collecting option_one votes and the other for collecting option_two votes, the pages in question in parameters option_one_vote_collection_page and option_two_vote_collection_page.

To simplify the process a tool-assisted procedure has been created for this purpose, as follows:

1. First of all come up with a succinct title for your poll. For instance if your poll question is "Jimbo Wales: yay or nay?", you might want to title your poll "Jimbo Wales". If it is instead the example question used here, "Do you believe that pending changes are the future when it comes to Wikipedia version control?", you could title it "Pending Changes".
2. Second, think of what your poll options should be. Which one should go first? Which one should go second? In the case of simple Yes/No polls, that orientation is standard, but otherwise the choice is yours.
3. To create the option_one_vote_collection_page, type the name of the page you are creating into the box below, replacing {POLL TITLE} with your poll title from step one and {OPTION_ONE} with the name of your first vote option from question two, and follow the instruction displayed once you hit the "Create" button. You may want to open this page in a second tab as hitting the button will take you away from this page.
   
4. To create the option_two_vote_collection_page, follow the same procedure but with reference to your second poll option this time:
   
5. Non-step: The templates will automatically configure the page for the text that will be preloaded into users' input when they vote. For instance, if I am a reader voting in the poll and I hit the Yes vote button, I naturally expect a corresponding text input to be created for me to save. In order to reduce the workload on pollsters and to reduce the amount of subpages that uses of the poll template will generate, this text input has been reduced to a simple reused string: Voting for option 1., Voting for option 2., and so on.
6. Finally it is time to set up a page for the poll itself. To do so use the following input to create the template, preferably at the same {POLL_TITLE} you used in steps 3 and 4:
   
7. Optional: Try voting to make sure that everything works!

Once all of this done, no further action is required: the templates handles vote counting, inputting, and display automatically.

How?

From a technical perspective this is made possible through two key technical uses abuses:

• The use of a Lua script to track the number of times a specific string has been inputted into a page: credit on this front to Mr. Stradivarius.
• The use of a CommentTitle input box and preloaded text to present the user with ready-made input that only needs to be saved in an aesthetically appealing way.

Other technical invocations:

• The use of parser functions to turn vote numbers into percentages, and from there into a stacked bar chart.
• The use of absolute positioning and image transparency to overlay a visually appealing graphic onto said chart.
• The use of absolute positioning to quietly hide the section title bar included in the CommentTitle input form (admit it; until you read this you didn't realize it was missing, did you?).

To do

• Add built-ins and preloads for semi-automating the poll setup procedures, particularly when it comes to vote counting.
• Add a capacity to return to the previous page after voting.
• Rigorous testing and bug-fixing.
• Add a capacity for closing the poll after a certain amount of time has elapsed.
• Add a capacity for not visualizing poll results until a certain minimum number of votes have accrued.
• Add a capacity for a third and maybe fourth polling option.