Marcos Silva
75 lines
2.3 KiB
Markdown
75 lines
2.3 KiB
Markdown
# 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.
|