Write Beautiful, High-Signal Documents in Telescopo

What Good Looks Like

Quick Cheat Sheet

Authoring Flow

1. Write section skeleton first (## headings only).
2. Add one-sentence purpose under each section.
3. Add examples (code/diagram/math) only where they reduce ambiguity.
4. Add a mini TOC for long docs.
5. Run a final pass for consistency in tone, naming, and spacing.

Markdown Structure and Rhythm

Use predictable rhythm. A strong pattern is: heading → one-sentence summary → bullet list or example.

## Why This Exists
One sentence that states the purpose.

## How It Works
- Input
- Processing
- Output

## Example
```json
{ "input": "X", "output": "Y" }
```

Headings and Anchors

Use headings as navigation nodes. Make them short and specific.

## Setup
## Data Model
## Rendering Pipeline
## Known Limitations

- [Setup](#setup)
- [Rendering Pipeline](#rendering-pipeline)

Lists and Tables

Use lists for decisions and actions

### Decision
- Keep markdown parser default behavior
- Override only image, code, heading renderers
- Add DOM tests for regression safety

Use tables for comparisons

| Option | Best For | Cost |
| --- | --- | --- |
| Minimal | Fast docs | Low |
| Structured | Team docs | Medium |
| Rigorous | Long-lived specs | High |

Links and Images

Write descriptive link text; avoid generic “click here”. Use images to clarify, not decorate.

Good: [View Architecture Overview](#architecture-overview)
Weak: [Click here](#architecture-overview)

![Rendering pipeline diagram](./images/rendering-pipeline.png "Renderer flow")

Code Blocks

Always set language where possible for syntax highlighting and readability.

```swift
func purchasePro() async throws {
    let result = try await product.purchase()
    // Handle verified transaction...
}
```

```json
{
  "feature": "pro_unlock",
  "enabled": true
}
```

Mermaid Diagram Principles

• One question per diagram (“what flow?”, “what states?”, “what sequence?”).
• Keep labels short; move explanation to text.
• Prefer several focused diagrams over one giant system map.

Flowchart Example

```mermaid
flowchart TD
  A[Open File] --> B{File Type}
  B -->|Markdown| C[Render Markdown]
  B -->|Mermaid| D[Render Diagram]
  B -->|LaTeX| E[Render Equations]
  C --> F[Display]
  D --> F
  E --> F
```

Sequence Diagram Example

```mermaid
sequenceDiagram
  participant U as User
  participant V as View
  participant R as Renderer
  U->>V: Open document
  V->>R: renderMarkdown(...)
  R-->>V: HTML output
  V-->>U: Display result
```

State Diagram Example

```mermaid
stateDiagram-v2
  [*] --> Idle
  Idle --> Rendering: open()
  Rendering --> Ready: success
  Rendering --> Error: failure
  Error --> Idle: retry
```

Gantt Diagram Example

```mermaid
gantt
  title Documentation Rollout
  dateFormat YYYY-MM-DD
  section Core
  Draft guide     :done, d1, 2026-02-01, 3d
  QA with fixtures:active, d2, after d1, 4d
  section Publish
  Website deploy  :d3, after d2, 2d
```

LaTeX Basics: Inline vs Display

Inline: The score is $S = \frac{p}{n}$.

Display:
$$
S = \frac{p}{n}
$$

Readable Equation Layout

Use aligned blocks for multi-step transformations.

$$
\begin{aligned}
L &= \frac{1}{n}\sum_{i=1}^{n}(y_i - \hat{y}_i)^2 \\
  &= \frac{1}{n}\left[(y_1-\hat{y}_1)^2 + \cdots + (y_n-\hat{y}_n)^2\right]
\end{aligned}
$$

Narrating Math

Always explain symbols in prose once.

Let $n$ be the number of samples and $p$ be the number of correct predictions.
Then accuracy is $A=\frac{p}{n}$.

Mixed-Format Patterns

Pattern: Explain → Diagram → Equation → Example

1. Explain system in two sentences
2. Show flow with Mermaid
3. Show formal relation with LaTeX
4. Close with realistic code or input/output example

Pattern: Spec writing with key labels

_input_: Lesson node from graph
_output_: Problem set aligned to constraints
_constraints_: grade band, topic, complexity

Mistakes to Avoid

Accessibility and UX

• Use descriptive link text.
• Add image alt text that describes meaning, not only appearance.
• Keep heading hierarchy logical (H2 → H3, avoid random jumps).
• Keep line length moderate and paragraphs short.

Starter Template (Copy/Paste)

# Document Title

## Summary
One-paragraph overview of the purpose and audience.

## Table of Contents
- [Architecture](#architecture)
- [Core Formula](#core-formula)
- [Implementation](#implementation)
- [Edge Cases](#edge-cases)

## Architecture
```mermaid
flowchart LR
  A[Input] --> B[Process]
  B --> C[Output]
```

## Core Formula
$$
f(x) = ax^2 + bx + c
$$

## Implementation
```swift
func runPipeline() {
    // concise, realistic example
}
```

## Edge Cases
- Missing input
- Invalid schema
- Timeout behavior

## References
- Internal links
- External docs
```

This guide is intentionally JavaScript-free for reliability and portability. If you want interactive enhancements on your site (copy buttons, collapsible sections, live preview), add JavaScript on top of this base.