docs: add pre-build tests, comment design, sharing drivers, and a polish checklist - #180
Open
roeku wants to merge 1 commit into
Open
docs: add pre-build tests, comment design, sharing drivers, and a polish checklist#180roeku wants to merge 1 commit into
roeku wants to merge 1 commit into
Conversation
…ish checklist Adds practical guidance drawn from building and shipping Devvit games. community_games.md - "Two tests before you build": does the game get better as more people play, and can it be played 100 days in a row. Names the two concepts that pass a surface review and still fail: parallel play (a session that leaves no trace in shared state) and straight ports of existing single-player games. - "Design for comments": the conditions that reliably invite comments, wiring the app and the thread together in both directions via the Reddit API and user actions, and crediting creators (links the existing attribution requirement in the Devvit Rules). - "Design for sharing": a table of sharing drivers and the mechanic that produces each one. feature-guide.mdx - "Design and polish checklist": concrete craft standards behind the existing "design and polish" consideration, covering recognizability, launch screen motion, asset consistency, emoji as UI, generic AI-generated styling, drag-and-drop scrolljacking, and validating user-generated content at submission. - The responsive design requirement says scrolling in inline webviews is prohibited but not what to do instead. Adds pagination and toggles as the alternative. Mirrored into versioned_docs/version-0.13 per the repo README.
Contributor
There was a problem hiding this comment.
Pull request overview
This PR expands existing Devvit docs with practical game-design guidance aimed at improving featuring readiness and sustained community engagement, mirrored across both docs/ and versioned_docs/version-0.13/.
Changes:
- Adds a “Design and polish checklist” to the featuring guide, plus a concrete alternative to prohibited inline-webview scrolling (pagination/toggles).
- Adds “Two tests before you build”, “Design for comments”, and “Design for sharing” sections to the community games best-practices guide.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| docs/guides/launch/feature-guide.mdx | Adds a design/polish checklist and clarifies responsive design guidance (avoid scroll containers; use pagination/toggles). |
| versioned_docs/version-0.13/guides/launch/feature-guide.mdx | Mirrors the featuring-guide updates into the v0.13 docs. |
| docs/guides/best-practices/community_games.md | Adds pre-build concept tests plus sections on driving comments and intentional sharing mechanics. |
| versioned_docs/version-0.13/guides/best-practices/community_games.md | Mirrors the community-games guidance into the v0.13 docs. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
|
|
||
| You cannot decide in advance how a community will talk about your game. Players routinely find a use you did not design for, fixate on a detail you thought was incidental, or invent a recurring joke that becomes the reason people come back. What you can control is whether commenting is worth doing at all. | ||
|
|
||
| These conditions reliably invite comment: |
|
|
||
| You cannot decide in advance how a community will talk about your game. Players routinely find a use you did not design for, fixate on a detail you thought was incidental, or invent a recurring joke that becomes the reason people come back. What you can control is whether commenting is worth doing at all. | ||
|
|
||
| These conditions reliably invite comment: |
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
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.
What this adds
Practical guidance drawn from building and shipping Devvit games. Everything lands in existing pages; no new files, no sidebar changes.
guides/best-practices/community_games.mdTwo tests before you build (new section, above Player retention)
Two go/no-go questions to run a concept through before writing code: does it get better as more people play, and can it be played 100 days in a row. The existing "scale from one to many" principle says the right thing, and this sharpens it: the steepness of the curve is the point, not just its direction. It also names the two shapes that pass a surface review and still fail, because both are common in submissions:
Design for comments (new section)
The docs list "community engagement" as a featuring consideration but do not say how to earn it. This covers the conditions that reliably invite comments (a shareable outcome, a genuine ambiguity, a human artifact, a visible mistake, an incomplete picture), wiring the app and the thread together in both directions, and crediting creators. The wiring points link to the Reddit API and to user actions, and the attribution point links to the existing requirement in the Devvit Rules rather than restating it.
It deliberately does not promise that you can predict the conversation. The recommendation is to ship, read the thread for a week, and build toward the conversation you actually got.
Design for sharing (new section)
A table of sharing drivers and the mechanic that produces each one, so developers can pick two or three on purpose instead of ending up with twelve by accident.
guides/launch/feature-guide.mdxDesign and polish checklist (new section, after Featuring considerations)
"Design and polish" is currently listed as a consideration with no definition. This makes it concrete: be recognizable in the feed, animate the launch screen tastefully, keep asset styles consistent, do not use emoji as UI elements, avoid generic AI-generated styling, do not capture the scroll gesture with drag-and-drop, and validate user-generated content at submission.
Responsive design requirement
The requirement says scrolling within inline webviews is prohibited but does not say what to do instead. Adds pagination and toggles as the alternative.
Notes for reviewers
versioned_docs/version-0.13per the repo README.**Tip**:callouts, tables for the driver list.docs/andversioned_docs/version-0.13/.I have completed the CLA.