docs: add a Tips and Tricks page - #1498
Conversation
Five things organisers routinely miss, led by the one that costs the most: election and race descriptions are rendered through formatMarkdown(), so [text](url) becomes a link and a bare URL does not. Nothing in the product says so outside the Details form, and a description that ends in a pasted address leaves voters copy-pasting it by hand. Also covered: where each description actually appears (and that neither appears on the results page), that titles are plain text, the dedicated candidate link field, and testing with a draft ballot first. Written against main; every claim is read off the current source rather than remembered. One tip was cut because it could not be verified from the code.
✅ Deploy Preview for bettervoting ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
📝 WalkthroughSummary by CodeRabbit
WalkthroughAdded a new Tips and Tricks help page. It documents formatted links, description placement, plain-text titles, candidate and party links, tie handling, and draft ballot testing. The page includes examples, tables, navigation metadata, and a contribution-guide link. Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
1 participant
Adds
docs/help/tips_and_tricks.md— a short page of things election organisers routinely miss. It's all existing behaviour; nothing here asks for a code change.The tip that prompted it: election and race descriptions go through
formatMarkdown(), so[text](url)becomes a real link — but a bare URL doesn't. OutsideElectionDetailsForm, nothing in the product says so, so descriptions ending in a pasted address are common, and voters end up selecting and copying the address by hand. On a phone that's a genuine obstacle.The other four:
election.titleandrace.titlerender straight through<Typography>, so markdown in a title displays literally.candidate_urlturns the name on the ballot into a link with an "opens in a new tab" icon — tidier than putting candidate URLs in the description, and not widely known.Every factual claim is read off
mainas of this branch rather than from memory. One tip — whether a description can still be edited once voting is open — was cut because I couldn't establish it from the code; happy to add it back if someone can confirm the rule.Style follows the existing
docs/help/pages: just-the-docs front matter,parent: BetterVoting Documentation,nav_order: 9(after Preliminary Results, before the99s). Internal links are relative.html, matching how the frontend already links todocs.bettervoting.com/help/preliminary_results.html.Happy to cut, reword, or split any of it — and if the page is better placed somewhere other than under Help, say the word.
Related
The discoverability gap is arguably a product issue rather than a docs one, so I've filed it separately as #1497. Short version:
a8efc073shipped the markdown feature with aSupports **bold** and [link text](url) formattinghelper under both Description fields; the RaceForm rewrite dropped that helper (authored before the markdown feature, landed after it, so the rebase removed a hint its author had never seen), and the new wizard's Description field never had one. The helper now survives only inElectionDetailsFormandSendEmailDialog. This page helps, but restoring the in-product hint would help more.