ai-for-dummies/submitted-skills/Marcos Silva/skills/unslop/references/house-style.md

Netcracker House Style

The voice and shape unslop rewrites toward when nothing else is specified. This is the default, not a mandate — pages with a stated owner voice override this list.

Sentence

• Active voice by default.
• One idea per sentence. Two if they're tightly coupled.
• Sentence length mostly 8–25 words. Long sentences only when the structure is parallel.
• No run-on lines (>200 chars) in body paragraphs. Code and tables exempt.

Paragraph

• First sentence carries the claim.
• Body sentences support it.
• Last sentence ties it to the next paragraph or to a link.
• 3–6 sentences for most paragraphs. Lists break up long paragraphs; they do not replace them.

Headings

• Verb-first when possible: "Run the migration" not "Migration".
• Question headings only when the body answers the question in the first sentence.
• No emoji in h1 / h2. Emoji ok in h3 and below when it's a stable convention.

Lists

• Parallel grammatical form across items.
• One concept per item. Two ideas → two items.
• Bullet list for unordered; numbered list for steps.

Tables

• Column headers in Title case.
• Numbers right-aligned in monospace columns; labels left-aligned in prose.
• Empty cells get <empty> or are filled — never blank.

Code

• Inline code for file names, env vars, commands, identifiers.
• Fenced blocks with language tag for anything longer than one line.
• Comments inside code blocks explain why, not what.

Links

• Anchor text describes the destination. "click here" is a smell.
• External links open in same tab; the Confluence renderer adds the indicator.
• Internal page links by title, not by URL — rename the page and the link follows.

Voice

• First person plural ("we") when the team owns the page.
• Third person when describing a component or a product.
• Avoid "I" on team-owned pages.
• Avoid the passive voice when it hides who did the thing.

What unslop does not change

• Code blocks, command output, error messages, log lines.
• Customer quotes (marked as such).
• Commit messages, ticket numbers, identifiers.
• Acronyms the audience uses.

Calibration

A page rewritten by unslop should pass the "would a senior engineer send this to their team?" test. If yes, ship. If the page still reads corporate, escalate to the owner — unslop is not the right tool for that.