From bdbbe8101eed3db2cf822ab27b3fb4dce39b0540 Mon Sep 17 00:00:00 2001 From: BlankR Date: Thu, 8 Jan 2026 01:00:24 -0800 Subject: [PATCH] update user guides --- docs/guides/flags.md | 25 ++++++++++- docs/guides/questions.md | 63 +++++++++++++++++++++++++++ docs/guides/reputation.md | 28 ++++++------ docs/guides/review.md | 89 ++++++++++++++++++++++++++++++++++++++- docs/guides/tags.md | 68 +++++++++++++++++++++++++++++- 5 files changed, 256 insertions(+), 17 deletions(-) diff --git a/docs/guides/flags.md b/docs/guides/flags.md index 304d04d368..047638f5b7 100644 --- a/docs/guides/flags.md +++ b/docs/guides/flags.md @@ -4,4 +4,27 @@ slug: /flags # Flags -User can flag the spam post. +Community members flag posts when they believe something violates guidelines: spam, offensive content, duplicates, or situations requiring moderator judgment. Each flag includes a category and optional comment. + +**Workflow:** +1. Open **Review → Flags**. +2. Review the flagged post alongside the reporter's reason and any previous flags or moderator actions. +3. Take action based on the flag type: + - **Spam/Offensive:** Delete the post and optionally suspend the author. + - **Duplicate:** Close the question with a link to the canonical duplicate. + - **Needs moderator attention:** Investigate the context, edit/close/delete as appropriate, or mark the flag as declined if no action is needed. +4. After handling, mark the flag as **Helpful** or **Declined** to close it. + +
+Best practices for flags + +- **Respond promptly:** Unaddressed flags pile up and make the queue harder to navigate. +- **Leave moderator notes:** If you decline a flag or take partial action, add a comment explaining your reasoning so other moderators understand the decision. +- **Watch for patterns:** Multiple flags on the same user may indicate a broader issue (serial spam, policy misunderstanding). Consider reaching out directly or applying a temporary restriction. +- **Use the right tool:** Delete for clear violations, close for duplicates or off-topic but non-harmful content, and edit for salvageable posts with minor issues. + +
+ +:::caution Flag abuse +If a user repeatedly submits false or malicious flags, use the **Admin → Users** panel to suspend their flagging privileges temporarily. +::: \ No newline at end of file diff --git a/docs/guides/questions.md b/docs/guides/questions.md index fe3cf15778..d158355699 100644 --- a/docs/guides/questions.md +++ b/docs/guides/questions.md @@ -4,14 +4,77 @@ slug: /questions # Questions +Every question moves through two independent axes: its moderation status (pending, normal, closed, deleted) and its visibility (pinned, listed, unlisted). Answers have their own lightweight review flow. Use the tables and collapsible reference below to keep conversations tidy without overwhelming readers. + +--- + ## Question status ![Question state diagram](/img/docs/questions-question-status.drawio.svg) +Questions always start as **Pending** when moderation is enabled. Once approved they become **Normal** entries that are eligible for answers, voting, and highlighting. Moderators can optionally **Close** normal questions (preventing new answers) or **Delete** them outright. Deleted questions remain restorable until purged. + +- **Approve** moves Pending to Normal. **Reject** sends Pending directly to Deleted, which hides it from everyone but moderators. +- **Unapprove** re-opens a Normal item for moderation (back to Pending) without erasing content, which is useful after large edits. +- **Close** freezes a Normal question while leaving it searchable; **Reopen** drops it back to Normal when the issue is resolved. +- **Delete** can happen from Pending, Normal, or Closed. **Undelete** revives the post, returning it to Pending (if it was never published) or Normal. + +
+When to leave a question Pending + +- Use Pending to pause low-effort or policy-sensitive submissions until they can be clarified. +- Add an internal comment before rejecting so other moderators understand the decision trail. + +
+ +
+Closing vs. deleting + +- Close when the content is valuable but the conversation needs to stop (duplicates, off-topic but informative, answered elsewhere). +- Delete when the content should not appear in search or feeds (spam, personal data). You can still undelete if needed. + +
+ ## Question visibility ![Question visibility diagram](/img/docs/questions-question-visibility.drawio.svg) +Status alone does not control prominence. Visibility lets you decide where a question is surfaced: + +- **Pinned**: Always shown at the top of list pages for its tags or spaces. Reserve for onboarding, policies, or featured announcements. +- **Visible (listed)**: Default state. Appears in feeds, search, tag pages, and widgets. +- **Unlisted**: Hidden from public lists but still accessible via direct URL. Great for private escalations or drafts shared with SMEs. + +Transitions are instant and lossless: + +- `Pin` promotes a visible item to the pinned slot; `Unpin` returns it to the standard list order. +- `Unlist` removes an item from feeds without deleting; `List` reintroduces it later. + +:::tip Keep visibility simple +Limit pinned questions to one or two per topic so learners do not scroll past walls of announcements. Pair unlisted items with a follow-up workflow (e.g., convert to documentation) so they do not languish. +::: + ## Answer status ![Answer state diagram](/img/docs/questions-answer-status.drawio.svg) + +Answer review mirrors the question workflow but skips closing and visibility controls: + +- **Pending** answers show only to moderators and the author until approved. +- **Normal** answers are fully public and can be voted or accepted. +- **Deleted** answers disappear from the thread but stay recoverable. + +
+Moderation actions + +- Approve or reject from the question’s Answers tab; rejected answers go straight to Deleted. +- Unapprove when an existing answer needs a second look after edits. +- Delete abusive or obsolete answers; Undelete restores them if context changes. + +
+ +## Best practices + +- Enable email or in-app notifications for the review queue so Pending items do not stall. +- Combine status and visibility intentionally (for example, Closed + Pinned for canonical FAQs, or Normal + Unlisted for invite-only betas). +- When you delete, leave a moderator note describing why; it travels with the revision history and speeds up future audits. diff --git a/docs/guides/reputation.md b/docs/guides/reputation.md index 34f3e133c6..a54eee89e5 100644 --- a/docs/guides/reputation.md +++ b/docs/guides/reputation.md @@ -4,26 +4,26 @@ slug: /reputation # Reputation -Reputation used to automate the management of community ecology. +Reputation automates moderation and rewards constructive participation. ## Reputation change rules | Condition | Change | -|---|---| -| Someone upvote your question | +10 | -| Someone upvote your answer | +10 | -| Someone accept your answer | +15 | -| You accept someone's answer | +2 | -| Your proposed was accepted | +2 | -| You downvote someone's answer | -1 | +|---|---:| +| Your question was upvoted | +10 | +| Your answer was upvoted | +10 | +| Your answer was accepted | +15 | +| You accepted an answer | +2 | +| Your suggested edit was accepted | +2 | +| You downvoted an answer | -1 | | Your question was downvoted | -2 | | Your answer was downvoted | -2 | ## Additional rules -- The initial reputation is `0`, after activation the reputation becomes `1` -- If there is an action that causes the user's reputation to be `< 1`, any subsequent actions that reduce the reputation will not reduce the user's reputation -- Maximum of `200` reputation per day -- If an action results in a user gaining `> 200` reputation for the day, any subsequent actions that increase reputation will not increase the user's reputation. -- The reputation gained from accepted answers is not limited by the `200` cap -- No reputation gained for accepting your own answer +- New accounts start with `0` reputation; it becomes `1` after account activation. +- Reputation cannot fall below `1`; once at `1`, further decreases that would take it below `1` are ignored. +- Users can earn a maximum of `200` reputation per UTC day. +- If reputation gains would push a user over `200` in a day, subsequent gains that day are ignored. +- Reputation from accepted answers is exempt from the `200` daily cap. +- No reputation is awarded for accepting your own answer. diff --git a/docs/guides/review.md b/docs/guides/review.md index 4fa4090be5..72038e8eee 100644 --- a/docs/guides/review.md +++ b/docs/guides/review.md @@ -4,4 +4,91 @@ slug: /review # Review -TODO +Review is the moderation layer that keeps content quality high while enabling community contributions. Moderators triage three streams: pending posts awaiting initial approval, suggested edits from lower-reputation users, and flagged content reported by the community. All reviews happen in a dedicated queue accessible via the admin menu, surfacing only items that require manual decision. + +--- + +## Pending posts + +When moderation is enabled (in **Admin → Settings → Write**) or an anti-spam plugin triggers, newly created questions, answers, or comments enter Pending status instead of publishing immediately. Authors see a "Waiting for review" message; everyone else sees nothing until approval. + +**Workflow:** +1. Navigate to **Review → Queued post**. +2. Each item displays the full content, author info (reputation, role, past contributions), tags (for questions), and any plugin-supplied reason. +3. Click **Approve** to publish (status moves to Normal) or **Reject** to delete (status moves to Deleted; author is notified). + +
+Tips for triaging pending posts + +- Check author reputation and history: first-time posters may need clarification, while high-reputation users rarely submit spam. +- Look for plugin indicators: if an anti-spam filter flagged it, review the reason before approving. +- For borderline cases, leave a comment on the post asking for edits, then return to the queue after the author responds. +- Rejected posts are soft-deleted; you can undelete them later if circumstances change. + +
+ +--- + +## Suggested edits + +Users below the "Edit without review" threshold submit changes as suggested edits. The original content remains visible while the proposal waits in a review queue. + +**Workflow:** +1. Go to **Review → Suggested Edits**. +2. A side-by-side diff highlights additions (green) and removals (red). +3. Click **Approve** to merge the edit, or **Reject** to discard and leave the original unchanged. + +
+When to approve edits + +- **Good edits:** Fix typos, add code formatting, clarify phrasing, insert relevant links, correct grammar, or update deprecated information. +- **Questionable edits:** Trivial changes (adding "thanks" or "hope this helps"), tag-only edits without substantive improvements, or changes that alter technical meaning without justification. +- **Bad edits:** Vandalism, promotional links, introducing errors, or overwriting correct content with wrong answers. + +If an edit is close but imperfect, consider approving it then making a follow-up edit yourself. + +
+ +
+Handling conflicting edits + +If multiple users suggest changes to the same post, you will see each proposal independently. Approve the best one first; remaining edits will be automatically invalidated if they conflict. You can also manually reject duplicates. + +
+ +--- + +## Flags + +Flags are community reports on posts or comments (spam, offensive, duplicate, moderator attention). Flagged items show reporter, reason, any plugin notes, and links to the post and its history. + +For full guidance and policy details, see the Flags guide: [Flags](flags.md). + +--- + +## Review permissions + +Access to review queues is governed by reputation thresholds. Default values and recommended settings: + +| Permission | Default reputation | Notes | +| --- | --- | --- | +| Edit others' questions/answers (needs review) | 100 | Submits as suggested edit | +| Edit tag description (needs review) | 100 | Submits as suggested edit | +| Review question edits | 1000 | Can approve/reject suggested edits to questions | +| Review answer edits | 1000 | Can approve/reject suggested edits to answers | +| Review tag edits | 2500 | Can approve/reject suggested edits to tag wikis | +| Edit others' questions/answers (without review) | 1000 | Bypasses review queue | +| Edit tag description (without review) | 10000 | Bypasses review queue | + +Adjust these in **Admin → Settings → Privileges** to match your community size. Smaller communities may lower thresholds to empower more moderators; larger communities may raise them to ensure experienced reviewers. + +--- + +## Automation and plugins + +Apache Answer supports anti-spam and content review plugins that can automatically: +- Hold low-reputation or suspicious posts for manual review. +- Reject or delete clear spam without moderator intervention. +- Tag posts with risk scores or reasons (e.g., "contains banned keywords"). + +Enable plugins in **Admin → Plugins** and configure thresholds in each plugin's settings. Combine automation with manual review to balance efficiency and accuracy. diff --git a/docs/guides/tags.md b/docs/guides/tags.md index ffcf13acb1..7a7c633916 100644 --- a/docs/guides/tags.md +++ b/docs/guides/tags.md @@ -4,4 +4,70 @@ slug: /tags # Tags -TODO +Tags keep threads discoverable, route questions to subject-matter experts, and drive notifications for followers. Use the sections below to jump between end-user tasks and moderator or admin workflows. + +## Common Usage + +| Action | Where | Key steps | +| --- | --- | --- | +| Browse tags | `/tags` | Search or sort by **Popular**, **Name**, or **Newest**; open a card for details. | +| Follow / unfollow | Tag card or tag header | Toggle **Follow** / **Following**, or edit the **Following tags** card on the sidebar in `/questions` path to batch-manage followed tags. | +| Tune notifications | Tag header → bell icon → **User settings → Notifications** | Enable **All new questions for following tags** for inbox/email alerts. | +| Add tags when asking | Ask form | Up to **5 tags** per post. Required/recommended tags highlight automatically. | + +## Asking with tags + +- The selector enforces the site's minimum/maximum tag rules and surfaces hints such as "Add at least two tags" when configured in Admin settings. +- Recommended tags float to the top; reserved tags show a badge and can only be added by moderators. +- Users with the `tag.add` permission can create tags inline via `+ Create "term"`. Display names and slugs share a 35-character limit. +- Keep the primary technology first, then add version or context tags. Avoid duplicates—use synonyms or merges instead. + +## Tag pages + +- `/tags/{slug}` shows the public landing page: excerpt, follow button, bell shortcut, and a sortable question list (**Newest**, **Active**, **Unanswered**, **Frequent**, **Score**). +- `/tags/{slug}/info` hosts the wiki with full Markdown content, edit history, and moderator actions (**Edit**, **Delete**, **Merge**, **Undelete**, **History**). + +
+Moderator workflows + +#### Create or edit tags + +1. Open `/tags/create` (roles 2 and 3). The form mirrors the inline modal and adds a rich-text editor for the wiki body. +2. After posting you land on `/tags/{slug}/info`; moderated sites may show a "Waiting for review" toast. +3. Future changes live at `/tags/{tag_id}/edit`, which includes an edit summary field and revision dropdown for quick rollbacks. + +**Guidelines** +- Display names and slugs share the `TAG_SLUG_NAME_MAX_LENGTH` limit (35 characters). +- The first paragraph becomes the excerpt for cards/search, auto-truncated to ~250 characters. +- Always fill the edit summary so the timeline stays readable. + +#### Maintain the wiki and synonyms + +- Click **Edit** on the wiki to update markdown; moderation queues may apply. +- Use the synonyms card → **Edit** to add or remove aliases, then **Save synonyms** to persist. +- Synonyms redirect legacy slugs to the canonical tag (`main_tag_slug_name`), keeping followers and counts unified. + +#### Merge, delete, restore + +- **Merge**: choose **Merge**, select a target tag, and Apache Answer migrates synonyms, followers, and tagged questions before converting the source to a synonym. +- **Delete**: allowed only when the tag has no questions or synonyms; otherwise a modal explains the blocker. Deleted tags display a red "Post deleted" banner. +- **Undelete**: available on deleted wikis; a confirmation modal restores the tag and metadata. + +
+ +
+Admin policies + +- **Recommend tags**: curated list pinned at the top of autocomplete; can also be enforced as required tags. +- **Set required tags**: forces each question to include at least one recommended tag. +- **Minimum tags per question**: numeric requirement (0–5) surfaced via the selector hint. +- **Reserved tags**: visible but only applicable by moderators; marked with a badge. + +
+ +## Best practices + +- Keep slugs short, lowercase, and stable—rename via **Edit** instead of deleting. +- Start every wiki with a concise summary; that paragraph powers tag cards and search previews. +- Use synonyms for spelling variants and merges for true duplicates so history and followers survive. +- Audit the tag list regularly: delete unused tags, reserve sensitive ones, and keep the recommended set aligned with community focus.