# Quantum Computing Article Writing Guide

This guide provides conventions and best practices for writing articles on quantum computing topics (gates, states, algorithms, concepts). Follow these patterns to maintain consistency across the quantum computing documentation.

## Article Structure

Every quantum computing article follows this general pattern:

1. **Title**: noun phrase identifying the topic (e.g., "Quantum Fourier Transform", "Entanglement")
2. **Opening paragraph**: bold term, concise definition, context and importance
3. **Definition section**: mathematical formalism and notation
4. **Subsections**: Properties, Applications, Implementation, Scalability, Relations
5. **Cross-references**: links to related concepts at end of article

## Opening Paragraph

The first paragraph establishes context and makes the article self-contained. Format:

- **Bold the main term** at the start: `**Quantum gate**`, `**Bell state**`, etc.
- Provide a **2–3 sentence definition** explaining what the concept is and why it matters
- Include **context**: where/how it's used, category (gate, state, algorithm, etc.)
- Avoid starting with "This article..." — be direct

Example:
> **Quantum Fourier Transform** is an $n$-qubit unitary gate that maps the computational basis state $|j\rangle$ to a uniform superposition with phases determined by $j$. It is the quantum analogue of the classical discrete Fourier transform and is a subroutine in Shor's factoring algorithm and phase estimation.

## Mathematical Notation

Use DokuWiki math mode (`$...$` for inline, `$$...$$` for block) consistently:

- **Inline math**: small expressions, ket notation, variable names. Example: `$|\psi\rangle$`, `$n$ qubits`
- **Block equations**: matrices, major formulas, derivations. Separate blank lines before/after
- **Ket notation**: use Unicode angle brackets directly (not `\langle`, `\rangle`). Example: `|Φ⁺⟩`, `|ψ⟩`
- **Operators**: bold or plain depending on emphasis. Example: `Z` operator, `**CNOT** gate`
- **Matrices**: format as `\begin{pmatrix}...\end{pmatrix}` for readability

Example block equation:
```
$$\text{QFT}|j\rangle = \frac{1}{\sqrt{2^n}} \sum_{k=0}^{2^n-1} e^{2\pi i jk/2^n} |k\rangle$$
```

## Sections and Subsections

### Standard Sections for Gates

1. **Definition**: Mathematical formalism, matrix representation, action on basis states
2. **Properties**: Unitarity, self-inverse, Clifford vs non-Clifford, symmetries
3. **Circuit Implementation**: Decomposition, gate count, circuit depth
4. **Applications**: Which algorithms use this gate and why
5. **Scalability**: Performance as $n$ increases, practical limits
6. **Relation to Other Gates**: Links to related concepts

### Standard Sections for States

1. **Definition**: Mathematical formalism, vector representation, eigenvalue information
2. **Properties**: Purity, entanglement, orthonormality, stability
3. **Construction**: How to prepare the state experimentally or via gates
4. **Measurement**: Measurement outcomes in different bases
5. **Applications**: Quantum algorithms and protocols that use this state
6. **Relation to Other States**: Links to related concepts

### Standard Sections for Algorithms

1. **Definition**: What problem does it solve and why it's interesting
2. **Overview**: High-level algorithm steps (pseudo-code style)
3. **Quantum Subroutines**: Detailed breakdown of quantum components
4. **Complexity**: Query complexity, circuit depth, resource requirements
5. **Applications**: Real-world problems this algorithm addresses
6. **Limitations**: Cases where the algorithm doesn't help or has high overhead
7. **Relation to Other Algorithms**: Links to related techniques

## Formatting Conventions

### Lists

**Use empty line before lists** and format list items as `- **bold**: description`:

```
## Key Properties

- **Unitarity**: $U^\dagger U = I$ (reversible operation)
- **Clifford property**: maps Paulis to Paulis (simulatable classically)
- **Error resilience**: robust to certain error types
```

### Bold for Key Terms

Bold the first instance of important terms within sections:

- **Superposition**: linear combination of basis states
- **Entanglement**: non-factorizable multi-qubit state
- **Unitary**: matrix $U$ satisfying $U^\dagger U = I$

### Internal Links

Link to related articles using `[[article-id|Display Text]]`:

- Link concepts to their dedicated pages: `[[quantum-gate-clifford|Clifford gates]]`
- Use descriptive link text that matches the article title style
- Don't embed links in headings (put them in the body text instead)

Example:
```
See [[quantum-gate-qft|Quantum Fourier Transform]] for applications in phase estimation.
```

### Code Comments (Rarely Used)

Only add comments when the code or concept is genuinely non-obvious:

- Avoid "This computes X" comments — the code structure already shows this
- Use comments for hidden constraints, subtle invariants, or workarounds
- Example: `# Bit-reversal reorders QFT output for compatibility with subsequent circuits`

## Levels of Detail

### When to Include vs. Omit

**Always include**:
- Definition and mathematical formalism
- How the concept is used in quantum computing
- Relations to other concepts (via links)
- Scalability challenges on near-term devices

**Include when relevant**:
- Explicit matrix representations (for gates/small states)
- Circuit diagrams (describe in text; actual diagrams handled separately)
- Experimental implementation details
- Approximations and optimizations

**Omit**:
- Proof sketches or detailed derivations (those belong in research papers)
- Historical anecdotes (focus on current utility)
- Trivial asides or disclaimers
- "In conclusion" summaries (let the content speak)

## Writing Tone

- **Technical but approachable**: explain from first principles before notation
- **Concise**: short paragraphs (3–6 sentences per idea), no fluff
- **Neutral**: "This gate is used in..." not "This gate is important for..."
- **Avoid**: superlatives ("amazing", "powerful"), qualitative judgments, marketing language

## Common Patterns

### Gate vs. Concept vs. Algorithm

**Gates** (e.g., `quantum-gate-cnot.md`):
- Unitary transformation of qubits
- Focus: definition, matrix, applications, decomposition
- Examples: CNOT, Hadamard, Toffoli

**Concepts** (e.g., `quantum-gate-clifford.md`):
- Category or property of multiple gates/states
- Focus: classification, why it matters, examples, implications
- Examples: Clifford gates, entanglement, stabilizer states

**Algorithms** (e.g., Grover's, Shor's):
- Computational procedure with quantum subroutines
- Focus: problem statement, algorithm steps, complexity, applications

### Two-Qubit vs. n-Qubit

**Category pages** (e.g., `quantum-gate-two-qubit.md`):
- Overview of gates/states in that class
- Link to individual pages
- Compare/contrast different instances
- Example: "Two-qubit gates enable entanglement between pairs"

**Individual pages** (e.g., `quantum-gate-cnot.md`):
- Deep dive into one specific gate/state
- Focus: definition, matrix, properties, applications
- Scalar content: properties specific to this gate

### Definition Patterns

**For gates**:
> **[Name]** is an $n$-qubit gate that [does what]. Its matrix is [form]. It is [key property: Clifford/non-Clifford, self-inverse, etc.].

**For states**:
> **[Name]** is an $n$-qubit state where [property]. It is an eigenstate of [operator] with eigenvalue [value]. It appears in [which algorithms/protocols].

**For concepts**:
> **[Concept]** is the set of [gates/states/objects] where [defining property]. They are important because [why they matter]. Examples include [list].

## Structure by Category

### Single-Qubit Gates (or States)
- Definition
- Matrix representation
- Bloch sphere representation (if relevant)
- Properties
- Applications
- Relation to other single-qubit gates

### Two-Qubit Gates (or States)
- Definition
- 4×4 matrix representation
- Basis action (how it transforms basis states)
- Entanglement properties
- Applications
- Decomposition into single-qubit + CNOT (if applicable)
- Relation to other two-qubit gates

### Multi-Qubit Gates (or States)
- Definition
- $2^n \times 2^n$ matrix (or abstract description if too large)
- Symmetries and special structure
- Scalability analysis
- Circuit implementation
- Applications
- Approximations (if any)

## Cross-Referencing Checklist

Before finishing an article, ensure:

- [ ] Definition section links to foundational concepts (gates use gates, states use states)
- [ ] Applications section mentions which algorithms/protocols rely on this
- [ ] Relations section links to similar or related concepts
- [ ] Scalability section mentions computational complexity
- [ ] Key terms are bolded on first mention
- [ ] Math notation is consistent (Unicode kets, no LaTeX in plain text)
- [ ] No dead links (verify linked pages exist)

## Common Mistakes to Avoid

1. **Starting with "This article..."** → Be direct with the definition
2. **Omitting the definition** → Every article needs mathematical formalism
3. **Inconsistent notation** → Decide on ket style, operator notation early
4. **Missing scalability** → Always mention how the concept scales with $n$
5. **Embedding links in headings** → Move to body text
6. **Over-explaining basics** → Link to foundational concepts instead
7. **Omitting applications** → Every concept should have at least one concrete use
8. **Generic or vague opening** → Be specific about what the article covers

## Examples of Well-Formed Articles

**Gate article**:
- `quantum-gate-qft.md` — comprehensive, includes circuit depth, approximations, applications
- `quantum-gate-cnot.md` — concise, clear applications, matrix representation

**State article**:
- `quantum-state-bell-00.md` — clear definition, properties, measurement, relations
- `quantum-state-ghz.md` — multi-qubit state with scalability discussion

**Concept article**:
- `quantum-gate-clifford.md` — classification, examples, implications, generator sets
- `quantum-state-entanglement.md` — types of entanglement, measures, applications

## Summary

Write quantum computing articles to be:
- **Self-contained**: reader understands concept without external references
- **Structured**: follow section conventions for the article type
- **Precise**: use correct mathematical notation and terminology
- **Connected**: link to related concepts
- **Practical**: include applications and scalability considerations

The goal is a personal knowledge base where each article is useful, findable, and connects naturally to related ideas.