Contribution guidelines for text fields (name, summary, getting going, quirks), good and bad examples #196

Summary

As a contributor, I want a short, concrete guideline with good and bad examples for the text I can enter on a device page (name now; summary, getting going and quirks when those fields open up), so that I know what is expected before I propose a change and my proposal is not bounced by the moderation checks for reasons I could not have known.

This is the content companion to the first contribution iteration in #74. Edit mode (#185) decides which fields a contributor can touch; this feature decides what good content in a text field looks like and gives the bot moderation its first rule set. It covers text only, in English; pictures are covered by the legal track (#35), translations are a separate item.

Working draft and single place for this work: OHF Device Database - Guidelines on user contributions (text). It already holds per-field definitions, good and bad examples with the reason for each verdict, a one-screen skeleton ("how to write device information"), a mapping from each writing rule to a bot capability and action (block, suggest, flag), open questions, and an appendix with how MusicBrainz, Wikipedia/Wikidata and OpenStreetMap handle the same problem plus samples from the sources in #27.

Fields covered

Each field gets a recipe, a length guide, a good/bad example table and a "never goes in" list. The five-point check (adds something, factual, specific, honest about certainty, short and in the right field) applies to all four.

Flow

• Group exercise. The draft is shared with the team and interested community members. Participants add their own good and bad examples per field and comment on the verdicts, so the examples reflect more than one view of what a summary adds over the structured data. Outcome is folded back into the draft.
• Decide the open questions that block the guideline from being final (section 7 and appendix C.5 of the draft): description vs summary as one or two fields; code blocks in getting going or links only; where safety warnings go; one English variety; claim basis as free-text hedging or a marker. Decisions are recorded on this issue.
• Reduce. The result is cut to a one-screen guideline (the skeleton) plus the example tables. Everything else stays in the draft as background.
• Publish at the point of entry. The one-screen version becomes the field help and placeholders in edit mode (Edit mode on the device page (website channel), reduced field set #185) and the summary modal; the full page lives on the DDB site next to the editorial stance and is linked from the form and from the contributor guidelines for the PR channel.
• Hand over the rule set. The rule-to-capability table (section 6 of the draft) is handed to the bot moderation feature as its initial checks, so bot behaviour and human guidance derive from the same source.
• Maintain. Changes to the guideline go through an issue in this repository; the bot rules change in the same step.

Acceptance criteria

• A guideline page exists on the DDB site covering name, summary, getting going and quirks, each with a recipe, a length guide, and at least five good and five bad examples with the reason for the verdict
• The one-screen version fits the edit-mode field help and placeholders without truncation and is linked to the full page
• Every rule in the guideline maps to a bot action (block, suggest or flag) or is explicitly marked as human judgement; the mapping is attached to the bot moderation feature
• The guideline records its decisions on description vs summary, code blocks, safety warnings and English variety
• Examples marked as unverified in the draft are either verified by a device owner or reworded so they illustrate style only
• A first-time contributor can read the one-screen version in under two minutes and write a name, summary, getting going and quirks entry that passes the five-point check without asking anyone (tested with at least three people outside the authoring group)
• The guideline is versioned and has a change process; the form links to the current version

Not in scope

• Guidelines for pictures, image rights and licence text (Launch readiness for the public Device Database (public information, communication, Preview/Labs exit) #35)
• Translations and guidelines in languages other than English
• Guidelines for structured fields (category, brand, local connection, traits); those follow from the schema, not from writing style
• Ingestion rules for external sources (Further enrichment from public databases #27); the draft's appendix C only informs the examples
• Trusted contributor tiers, reputation, review UI (increments from Stage 3: Accounts and editing #152)

Dependencies

• Edit mode (Edit mode on the device page (website channel), reduced field set #185) for where the field help and placeholders are shown
• Bot moderation feature (under Add way to contribute by modifying data on an existing device #74) as the consumer of the rule-to-capability table
• Schema decisions on description vs summary, getting going sub-slots (pair, unpair, factory reset, wake) and a claim-basis marker, since these change the fields the guideline describes
• Editorial stance page on the DDB site as the voice the guideline applies field by field
• Group exercise participants: at least the DDB team plus two or three community contributors with devices on hand

Open questions