docs: group the help pages into three sections - #1505
Draft
masiarek wants to merge 1 commit into
Draft
Conversation
Proposal for discussion, not an urgent change. Opening it as a draft so the shape can be argued before any content is written against it. Adds three section pages under BetterVoting Documentation and re-parents the existing seven help pages into them: Setting Up Your Election Paper Ballots, Security Options Counting and Results Hand Count, Ties, Preliminary Results Reference FAQ, How to enable beta features The property that makes this cheap to try: **no file moves and no URL changes**. just-the-docs builds the sidebar from `parent:` front matter, not from directory layout -- index.md at the docs root is already the parent of help/faq.md in a subfolder, so nesting is independent of where files live. Every existing page keeps its exact URL, including the six the app hardcodes and the two deep anchors (ties.html#random-tie-breakers, faq.html#write-in-scores-not-counted). Verified by building and checking each one. That also means this is reversible with a one-line edit per page, which is why it seemed worth showing rather than describing. Why sections at all, given there are only seven pages: at this size a flat list is arguably better, and if that's the conclusion, closing this is a fine outcome. The reason to settle it now is that there is a large backlog of unpublished help content, and agreeing where things go before writing avoids re-litigating placement on every content PR. Grouping follows the election lifecycle -- before the vote, during and after, then reference -- which is what Simply Voting's help site uses and what BV's own election states map onto naturally.
✅ Deploy Preview for bettervoting ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Draft — this is a proposal for discussion, not something that needs merging soon. Opening it as a PR rather than an issue because the shape is easier to judge when you can see it rendered.
Groups the help pages into three sections, following the election lifecycle:
No files move and no URLs change
This is the part that makes it cheap to try. just-the-docs builds the sidebar from
parent:front matter, not from directory layout —index.mdat the docs root is already the parent ofhelp/faq.mdin a subfolder, so nesting is independent of where files live.So every page keeps its exact URL, including the six the app hardcodes and both deep anchors. Verified against a local build:
/help/paper_ballots.html,/help/hand_count.html,/help/ties.html,/help/faq.html,/help/preliminary_results.html— all unchangedties.html#random-tie-breakersandfaq.html#write-in-scores-not-counted— both anchors still presentIt's also reversible with a one-line edit per page, which is why it seemed worth showing rather than just describing.
Why now, given there are only seven pages
Honestly: at this size a flat list is arguably better, and if that's the conclusion, closing this is a perfectly good outcome.
The reason to settle it now is the backlog — there's a lot of help content written but unpublished, and agreeing where things go before writing avoids re-litigating placement on every content PR. The grouping follows the election lifecycle (before the vote → during and after → reference), which is what Simply Voting's help site uses and what BV's own election states map onto naturally.
Interaction with #1502
#1502 adds an Election States page with
parent: BetterVoting Documentation. If both are wanted, whichever merges second needs a one-line front-matter update — Election States belongs under Setting Up Your Election. Happy to rebase whichever way suits; they're otherwise independent.Background
I sketched this out while looking at how other election platforms organise their help sites (Simply Voting, ElectionBuddy, Election Runner, VotingApp). Those notes are here if the reasoning is useful — they're working notes rather than a polished proposal, so they're blunt in places, and the specific nav in them is more ambitious than what this PR does.