Document Content Writing Editing

Hierarchy checklist:

• Document has a clear title
• Introduction or summary appears before any section heading
• Sections flow from general to specific
• Each section has a single coherent topic
• Conclusion or next steps are explicit

3. Technical Writing vs. Prose Writing

Technical Writing

• Precision over elegance. Every term must be unambiguous.
• Use consistent terminology throughout — never swap synonyms for variety.
• Prefer active voice and imperative mood for instructions: "Run the command" not "The command should be run."
• Define acronyms and technical terms on first use.
• Use numbered steps for sequential procedures; bullet lists for non-sequential options.
• Avoid hedging language ("It is important to note that...") — state facts directly.
• Include examples, code snippets, and concrete values wherever abstract descriptions might confuse.

Prose Writing

• Vary sentence length and structure for rhythm.
• Use transitions between paragraphs to maintain flow.
• Show, don't tell — use specific details rather than generalities.
• Avoid business jargon and filler phrases ("leverage synergies", "moving forward", "at the end of the day").

4. Long-Form Article Writing

When writing articles, blog posts, guides, tutorials, essays, or newsletters:

Core rules:

1. Lead with the concrete thing: example, output, anecdote, number, or code block.
2. Explain after the example, not before.
3. Prefer short, direct sentences over padded ones.
4. Use specific numbers when available and sourced.
5. Never invent biographical facts, company metrics, or customer evidence.

Banned patterns — delete and rewrite any of these:

• Generic openings like "In today's rapidly evolving landscape"
• Filler transitions such as "Moreover" and "Furthermore"
• Hype phrases like "game-changer", "cutting-edge", or "revolutionary"
• Vague claims without evidence
• Credibility claims not backed by provided context

Voice capture: If the user wants a specific voice, collect published articles, newsletters, or posts. Extract sentence length and rhythm, formality level, favored rhetorical devices, and formatting habits. Default to a direct, operator-style voice: concrete, practical, and low on hype.

Structure by article type:

• Technical guides: open with what the reader gets; use code or terminal examples in every major section; end with concrete takeaways, not a soft summary.
• Essays / opinion pieces: start with tension, contradiction, or a sharp observation; keep one argument thread per section.
• Newsletters: keep the first screen strong; mix insight with updates; use clear section labels and easy skim structure.

5. Writing READMEs and Project Documentation

A README is a project's front door. Use this structure:

# Project Name
One-sentence description of what it does and who it is for.

## Overview
2–4 sentences expanding on the description, with key use cases.

## Prerequisites
What the reader needs before they start.

## Installation
Step-by-step setup instructions.

## Usage
Concrete examples with real commands and expected output.

## Configuration
Key options, environment variables, config file structure.

## API Reference (if applicable)
Functions, endpoints, parameters, return values.

## Contributing
How to submit issues, pull requests, coding standards.

## License

README best practices:

• Lead with value, not history. First paragraph answers "why should I use this?"
• Include at least one working code example in the Usage section.
• Keep installation steps numbered and copy-pasteable — test every command.
• Link to longer documentation rather than embedding it — READMEs should be scannable.

6. Editing and Improving Existing Content

1. Read the full document before making any changes.
2. Identify the problem category: clarity, structure, tone, completeness, accuracy, or style.
3. Preserve the author's voice unless explicitly asked to change it.
4. Do exactly what was asked — do not expand scope.
5. Flag rather than silently fix substantive issues.

7. Multi-Platform Content Distribution

When distributing content across social platforms, adapt for each — never cross-post identical copy.

Platform specifications:

Repurposing flow:

1. Start with an anchor asset (article, video, demo, memo)
2. Extract 3-7 atomic ideas
3. Write platform-native variants
4. Trim repetition across outputs
5. Align CTAs with platform intent

Rules:

• Primary platform first — draft the main platform version, then adapt for others.
• Hooks matter more than summaries.
• Every post carries one clear idea.
• Use specifics over slogans. Keep the ask small and clear.

8. Code Documentation: Docstrings, Comments, and API Docs

Docstrings

• Describe what the function/class does, not how it does it.
• Include: purpose, parameters (name, type, description), return value, and exceptions raised.
• Keep docstrings current when the implementation changes.

Summary line: one sentence, imperative mood ("Return the filtered list").

Args:
    param_name (type): Description of what it represents.

Returns:
    type: Description of the return value.

Raises:
    ErrorType: When and why this error is raised.

Inline Comments

• Comment the why, not the what. If code is clear, a comment restating it adds noise.
• Comment non-obvious logic, workarounds, magic numbers, and performance-critical choices.
• Keep comments updated — a wrong comment is worse than no comment.

API Documentation

• Document every endpoint with: description, parameters, request body, response schema, error codes, and at least one example.
• Show real example requests and responses — use realistic but non-sensitive placeholder values.

9. Tone, Style, and Formatting Standards

Core tone guidelines (default):

• Friendly and competent, but neutral — like a knowledgeable colleague, not a marketer.
• Use plain language. If a simpler word works equally well, use it.
• Use gender-neutral language. When a person's pronoun is unknown, use "they."
• Do not use emojis in professional or technical documents unless explicitly requested.
• Do not use exclamation points in technical documentation.

Markdown formatting rules:

• # — Document title only (one per document)
• ## — Major sections; ### — Subsections. Avoid #### except in highly structured technical references.
• Use sentence case for headings unless style guide specifies title case.
• Use unordered lists for non-sequential items; ordered lists only for steps where order matters.
• Never nest lists more than two levels deep.
• Never have a list with only one item — use a sentence instead.
• Bold for key terms and important warnings. Italic for titles or technical terms on first use. Code formatting for all code, file paths, commands, and config values.
• Use tables for comparisons, not lists.
• Always specify the language for code blocks: ```python, ```bash.

10. Research-Backed Writing with Citations

When writing content that draws on sources:

• Cite inline, directly after the sentence or claim the source supports.
• Cite up to three sources per claim — more signals the claim needs to be broken up.
• Never reproduce copyrighted content verbatim. Paraphrase and cite.
• Use an unbiased, journalistic tone. Avoid advocacy language unless the document is explicitly persuasive.
• When sources conflict, note the conflict and explain which source you weighted and why.
• Begin with a summary of findings before diving into detail.
• Never start a research-backed document with a heading — lead with a prose introduction.

11. Output Quality Standards

Every piece of writing must meet these standards before delivery:

• Accuracy: Claims are factually correct or clearly marked as uncertain
• Completeness: The document addresses all parts of the request
• Clarity: Each sentence has one clear meaning
• Concision: No filler, no redundancy — every sentence earns its place
• Consistency: Terminology, formatting, and tone are uniform throughout
• Correctness: Grammar, spelling, and punctuation are correct
• Actionability: Instructions are specific enough to follow without guessing

Do not summarize what you wrote at the end of the document unless a summary section is a logical part of the document type. Do not add meta-commentary directed at the user within the document itself. The document should read as if written by a human expert for its intended audience.