Ivan's wiki

Site Tools

quantum-writing-guide

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
quantum-writing-guide [August 22, 2026 at 23:09] – Ivan Janevskiquantum-writing-guide [August 26, 2026 at 15:46] (current) – external edit 127.0.0.1
Line 1: Line 1:
-# Quantum Computing Article Writing Guide+# 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.+Writing conventions for quantum computing topics (gates, states, algorithms, concepts).
  
-## Article Structure+## Article structure
  
-Every quantum computing article follows this general pattern:+1. **Opening paragraph**: bold term, 2–3 sentence definition, context and importance 
 +2. **Definition**: mathematical formalism, matrix representation (for gates/states) 
 +3. **Subsections**: Properties, Applications, Implementation, Scalability, Relations (choose relevant ones) 
 +4. **Cross-references**: links to related concepts
  
-1. **Title**: noun phrase identifying the topic (e.g., "Quantum Fourier Transform", "Entanglement") +Example opening: 
-2. **Opening paragraph**: bold term, concise definition, context and importance +> **Quantum Fourier Transform** is an $n$-qubit unitary gate mapping computational basis state $|j\rangle$ to a superposition with phases determined by $j$. It is the quantum analogue of the discrete Fourier transform and appears in Shor's factoring and phase estimation algorithms.
-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+## Math notation
  
-The first paragraph establishes context and makes the article self-contained. Format:+- **Inline**: `$|\psi\rangle$`, `$n$ qubits` (use LaTeX, not Unicode) 
 +- **Block equations**: matrices, major formulas (blank lines before/after) 
 +- **Kets**: `$|\psi\rangle$` in body (LaTeX); Unicode `|ψ⟩` only in article titles 
 +- **Operators**: plain text or **bold** by emphasis (e.g., `Z` operator, **CNOT** gate) 
 +- **Matrices**: use `\begin{pmatrix}...\end{pmatrix}`
  
-- **Bold the main term** at the start: `**Quantum gate**`, `**Bell state**`, etc. +## Sections by type
-- 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: +**Gates**: Definition, Properties, Circuit Implementation, Applications, Scalability, Relations
-> **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+**States**: Definition, Properties, Construction, Measurement, Applications, Relations
  
-Use DokuWiki math mode (`$...$` for inline, `$$...$$` for block) consistently:+**Algorithms**: Problem statement, Overview, Quantum Subroutines, Complexity, Applications, Limitations, Relations
  
-- **Inline math**: small expressions, ket notation, variable names. Example: `$|\psi\rangle$`, `$n$ qubits` +## Formatting
-- **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: +- **Lists**: use `- **term**: description` format with blank line before 
-``` +- **Bold**: mark first mention of key terms in each section 
-$$\text{QFT}|j\rangle = \frac{1}{\sqrt{2^n}} \sum_{k=0}^{2^n-1} e^{2\pi i jk/2^n} |k\rangle$$ +- **Internal links**: use `[[article-id|Display Text]]` in body text, never in headings 
-```+- **Headings**: sentence case, never title case (first word capitalized, rest lowercase unless proper nouns) 
 +- **Article titles**: sentence case, not title case
  
-## Sections and Subsections+## Scope
  
-### Standard Sections for Gates+**Always**: definition, formalism, applications, relations, scalability
  
-1. **Definition**: Mathematical formalism, matrix representation, action on basis states +**When relevant**: matrix representations, circuit diagrams (text descriptions), implementation details, approximations
-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+**Omit**: proofs and derivations, historical anecdotes, trivial asides, "in conclusion" summaries
  
-1. **Definition**: Mathematical formalism, vector representation, eigenvalue information +## Tone
-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+Technical but approachable. Short paragraphs (3–6 sentences). Neutral ("is used in" not "is important for"). No superlatives or marketing language.
  
-1. **Definition**: What problem does it solve and why it's interesting +## Definition templates
-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+**Gate**: **[Name]** is an $n$-qubit gate that [action]. Its matrix is [form]. It is [Clifford/non-Clifford, self-inverse, etc.].
  
-### Lists+**State**: **[Name]** is an $n$-qubit state where [property]. It is an eigenstate of [operator] with eigenvalue [value]. Applications: [algorithms/protocols].
  
-**Use empty line before lists** and format list items as `- **bold**: description`:+**Concept**: **[Name]** is the set of [gates/states] where [defining property]. Examples: [list].
  
-``` +## Common mistakes to avoid
-## Key Properties+
  
-- **Unitarity**: $U^\dagger U = I$ (reversible operation) +- Starting with "This article..." instead of being direct 
-- **Clifford property**: maps Paulis to Paulis (simulatable classically) +- Omitting definition or mathematical formalism 
-- **Error resilience**: robust to certain error types +- Inconsistent notation (choose ket style early) 
-```+- Missing scalability analysis 
 +- Embedding links in headings 
 +- Over-explaining basics instead of linking to them 
 +- No applications mentioned 
 +- Generic opening paragraph
  
-### Bold for Key Terms+## Before publishing
  
-Bold the first instance of important terms within sections: +- Definition links to foundational concepts 
- +- Applications mention relevant algorithms/protocols 
-- **Superposition**: linear combination of basis states +- Relations section links to similar concepts 
-- **Entanglement**: non-factorizable multi-qubit state +- Scalability mentioned 
-- **Unitary**: matrix $U$ satisfying $U^\dagger U = I$ +- Key terms bolded on first mention 
- +- Math notation consistent (LaTeX in body, Unicode only in titles) 
-### Internal Links +- No dead 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.+
  
quantum-writing-guide.1787440179.md.gz · Last modified: by Ivan Janevski