wireless-docs/docs/AUTHORING_GUIDELINES.md

Typst Documentation Authoring Guidelines

This document provides comprehensive authoring guidelines for the EID Wireless documentation written in Typst.

---

1. Voice and Tone

General Approach

• Technical but approachable: Explain complex technical concepts clearly without oversimplifying
• Use examples and analogies: Concrete examples help readers understand abstract concepts
• Direct and conversational: Use second-person perspective and active voice when appropriate
• Confident and authoritative: The documentation presents established facts and proven principles

Voice Characteristics

// Example of technical but approachable tone (from core.typ:25-27)
#callout(kind: "tip", label: "Key Point")[
  Stationary items only begin to fall when their $"age" + "id"$ is a multiple of $4$.
]

The documentation explains technical details clearly:

• Uses precise terminology ("stationary items," "mod 4 cycle")
• Provides context and explanation for why things work
• Avoids jargon without explanation

Examples from the Documentation

The documentation frequently uses:

1. Direct explanation: "Recall that any entity spawning will increment the ID counter"
2. Examples with concrete scenarios: Step-by-step walkthroughs of entity spawning
3. Mathematical reasoning: Clear derivation of relationships with mod arithmetic
4. Practical implications: "Therefore B falls at time $t=2$"

---

2. Formatting Conventions

Mathematical Notation

• Use $...$ for inline math: $"age"_(A, 1) = "age"_(A, 0) + 1$
• Use & for alignment in multi-line equations
• Use (mod N) notation for modular arithmetic: $... equiv 0 &(mod 4)$

Important: The documentation uses a specific notation for modular arithmetic:

$ "age"_(A, 0) + 1 + "id"_A & equiv 0 (mod 4) $

Code Blocks

• Use triple backticks with language specifier: ```` ```mc-diorama` ``
• The documentation defines a custom diorama format for Minecraft diagrams
• Java code blocks use: ```java

Example from core.typ:41-67:

public class ItemEntity extends Entity {
  public void tick() {
    ...
    if (this.onGround() && !(this.getDeltaMovement().horizontalDistanceSqr() > (double)1.0E-5F) && (this.tickCount + this.getId()) % 4 != 0) {
      ...
    } else {
      this.move(MoverType.SELF, this.getDeltaMovement());
      ...
    }
    ...
  }
}

Block References

• Use @symbol syntax to reference sections: @singleplayer, @paper, @tilesets
• Use @block-priority, @block-delay, @observer-bug for subsections

Section Headers

• Use = for level 1 headings (chapters): = Core Mechanics
• Use == for level 2 headings (sections): == Entity IDs
• Use === for level 3 headings (subsections): === Daylight Detector

Example from core.typ:3:

= Core Mechanics <core>
== Entity IDs

The <core> syntax creates an anchor/ID for the section.

---

3. Interactive Elements (Dioramas)

What is a Diorama?

A diorama is an interactive visualization of Minecraft redstone mechanisms. The documentation uses custom mc-diorama blocks that render as interactive HTML elements.

Integration Syntax

Dioramas are integrated using the #show directive in lib.typ:

#show raw.where(lang: "mc-diorama"): it => diorama(
  autoplay: true,
  loop: true,
  radius: 5,
  theta: 25,
  phi: 25,
  it.text,
)

This directive tells Typst to:

1. Find all blocks with language mc-diorama
2. Wrap them in the diorama() function
3. Pass the block content as it.text

Diorama Parameters

Common parameters include:

• autoplay: true - Start animation automatically
• loop: true - Repeat animation when finished
• orbit: true - Enable orbit camera controls
• pan: true - Enable pan camera controls
• zoom: true - Enable zoom controls
• radius, theta, phi - Camera position
• speed - Animation speed

Example from tilesets.typ:15-23:

#show raw.where(lang: "mc-diorama"): it => diorama(
  orbit: true,
  pan: true,
  zoom: true,
  autoplay: true,
  theta: 160,
  phi: 20,
  it.text,
)

Diorama Content Format

Diorama content uses a custom format:

p x y z block_type properties
t time

Where:

• p = place/modify a block at coordinates
• t = advance time to specified tick
• Properties are space-separated key=value pairs

Example from design.typ:17-49:

p 0 0 0 smooth_stone_slab type=top
p 0 1 0 daylight_detector inverted=true power=1
p 0 2 0 piston facing=east extended=false
t 0
p 0 2 0 extended=true
t 1
p 0.5 2 0 piston_head facing=east short=true type=normal

Timeline Format

The diorama uses a timeline-based animation system:

• t N advances the timeline to tick N
• Changes between ticks are interpolated
• Multiple changes can be made at the same tick

---

4. Stylistic Patterns

Callouts

Callouts are defined in lib.typ:1-10 and used extensively throughout the documentation:

#let callout(body, kind: none, label: none, outlined: false) = {
  html.section(
    class: ("callout", kind),
    context {
      let level = counter(heading).get().len() + 1
      heading(label + ":", level: level, numbering: none, outlined: outlined)
      body
    },
  )
}

Types of Callouts

1. Tip: #tip[Content] - Helpful suggestions or insights
2. Note: #note[Content] - Important information or clarifications
3. Warning: #warn[Content] - Critical warnings or cautions
4. Todo: #todo[label, body] - Notes for future work

Example and Solution Blocks

These are currently implemented as TODO callouts but are planned to be proper elements:

#let example(body) = todo("example", body)
#let solution(body) = todo("solution", body)

Example from core.typ:83-116:

#example[
  For example, suppose we spawn an item $A$, then 2 game ticks later we spawn an item $B$...
  
  #solution[
    To simplify the arithmetic, orient everything around $t=0$...
  ]
]

Details Block

The details function is defined but commented out, suggesting it's planned for expansion:

#let details(body, label: none) = {
  todo(label, body)
  // html.details({
  //   if label != none {
  //     html.summary(label)
  //   }
  //   body
  // })
}

HTML Integration

The documentation uses HTML elements for interactive components:

From design.typ:128-135:

#html.div(id: "atlas-container", style: "position: fixed; left: 0; top: 0; border 1px solid white;")
#html.script(
  "
document.onreadystatechange = () => {
document.getElementById('atlas-container')?.appendChild(window.mcEngine.atlas.canvas)
}
",
)

---

5. Structuring Technical Explanations

Problem → Solution Format

The documentation frequently follows this pattern:

1. Present the problem or phenomenon
2. Explain the underlying mechanism
3. Show the mathematical reasoning
4. Provide concrete examples
5. Draw conclusions

Example from core.typ:77-227:

== Observable Drop Delay
[Problem] We can't control absolute entity ID but can compare them
[Explanation] Use reference items to predict behavior
[Example 1] Simple two-item comparison with math derivation
[Example 2] Four-item scenario showing pattern recognition
[Example 3] Broken pattern analysis to determine entity spawns

Mathematical Explanations

When explaining mathematics, the documentation uses:

1. State the relation: "$"age"_(A, 0) + 1 + "id"_A equiv 0 (mod 4)$"
2. Substitute known values: "Item A has ID before B, so $"id"_A = "id"_B - 1$"
3. Show derivation: Multi-line equation with alignment
4. State conclusion: "A must fall at t=0."

Example from core.typ:107-116:

So take the relation for $A$ and substitute in these values for $B$.

$
          "age"_(A, 0) + 1 + "id"_A & equiv 0 (mod 4) \
  "age"_(B, 0) + 2 + 1 + "id"_B - 1 & equiv 0 (mod 4) \
          "age"_(B, 0) + 2 + "id"_B & equiv 0 (mod 4) \
$

Compare with the relation for $B$ and we see that $x=2$.

#callout(kind: "tip", label: "Therefore:")[$B$ falls at time $t=2$.
]

Java Code Documentation

When showing Java code:

1. Include only relevant sections: Don't show entire classes, just the important parts
2. Add context with notes: Use #note[] to explain what code does
3. Highlight key lines: The documentation shows full code but focuses reader attention

Example from core.typ:38-52:

#note[ `onGround` is only ever updated via `move`, and this branch is the *only* place that
  `ItemEntity.move` is called. `tickCount` is the item's age. ]

```java
public class ItemEntity extends Entity {
  public void tick() {
    ...
    if (this.onGround() && !(this.getDeltaMovement().horizontalDistanceSqr() > (double)1.0E-5F) && (this.tickCount + this.getId()) % 4 != 0) {
      ...
    } else {
      this.move(MoverType.SELF, this.getDeltaMovement());
      ...
    }
    ...
  }
}

---

## 6. Relationship Between Text and Interactive Visualizations

### Dioramas as Explanatory Tools
Dioramas are not just decorative—they are integral to understanding:

1. **Before reading, see the phenomenon**: Dioramas show what happens first
2. **Then read the explanation**: Text explains why it happens
3. **Then verify understanding**: Readers can manipulate the diorama

**Pattern from tilesets.typ:15-56**:
```typ
#show raw.where(lang: "mc-diorama"): it => diorama(...)

```mc-diorama
p 0 -1 0 smooth_stone_slab type=top
p 1 -1 0 smooth_stone_slab type=top
... (animation showing tile sequence)
t 20
p 0 0 0

The diorama appears *before* the textual explanation, allowing readers to observe first.

### Text Supporting Visualization
Text always complements the diorama by:

1. **Explaining what to look for**: "Note how the redstone signal propagates in order"
2. **Providing context**: "This 4gt tileset demonstrates binary encoding"
3. **Giving the mathematical basis**: "We identify higher priority with 0, lower with 1"

### Multiple Perspectives
Complex concepts are shown from multiple angles:

**Example: Tilesets in tilesets.typ**
1. **Full diorama** showing the complete system (lines 15-56)
2. **Numeric representation** showing the encoding (lines 254-263)
3. **Abstract diagram** showing the bit pattern (line 268)
4. **Another diorama** showing arbitrary values (lines 270-297)

This multi-modal approach helps different learning styles.

### Interactive vs. Static
The documentation uses:
- **Autoplay loops** for demonstrating processes: `autoplay: true, loop: true`
- **Manual control** for exploration: `orbit: true, pan: true, zoom: true`
- **Static cameras** for focused attention: `orbit: false`

---

## 7. Additional Conventions

### File Organization
- Content files are in `/content/` directory
- Library definitions in `/lib.typ`
- Main document in `/main.typ`
- Each content file corresponds to a web page

### Linking
External links use `#link("URL")[text]`:
```typ
#link("https://youtu.be/81OV1BltMQ8")[iPlayGames's Wireless Masterclass]
#link("https://minecraft.wiki/w/Entity#Types_of_entities")[The Minecraft Wiki]

Cross-References

Use @symbol for internal references:

See @singleplayer for details.
See @paper for details.
See @tilesets for details.

TODO System

The documentation uses #todo[label, body] for planning:

#todo["Network Protocol" is inaccurate]
#todo[Singleplayer patch links][figure out exact version compatibility list.]

Block References

Special section anchors use <name> syntax:

== Entity IDs <core>
== Stationary Item Optimization <singleplayer>
== Paper Servers <paper>
= Tilesets <tilesets>

---

8. Best Practices for Authors

When Writing New Content

1. Start with a diorama showing the phenomenon or system
2. Explain the mechanism with clear, concise language
3. Provide mathematical justification when appropriate
4. Give concrete examples with step-by-step reasoning
5. Use callouts for key takeaways and warnings
6. Reference existing sections rather than repeating information

When Creating Dioramas

1. Use autoplay for demonstrations of recurring patterns
2. Enable orbit/pan/zoom for complex systems readers should explore
3. Keep timelines explicit with clear t N markers
4. Show before/after states to demonstrate changes
5. Use appropriate scaling—don't overcrowd the view

Mathematical Writing

1. Define all variables before using them
2. Show derivation steps clearly with alignment
3. Use consistent notation throughout
4. Explain the mod arithmetic thoroughly
5. Connect math to implementation with code examples

---

9. Template for New Sections

Here's a recommended template for new documentation sections:

#show raw.where(lang: "mc-diorama"): it => diorama(
  autoplay: true,
  loop: true,
  radius: 5,
  theta: 25,
  phi: 25,
  it.text,
)

= Section Title <section-name>

== subsection

```mc-diorama
p 0 0 0 block_type
p 0 1 0 another_block
t 0
p 0 0 0 changed_block
t 10
p 0 0 0

Explanation of what's happening, why it matters, and how it works.

#example[ Concrete example with step-by-step walkthrough.

#solution[ Solution or explanation of the example. ] ]

#callout(kind: "tip", label: "Key Insight")[ Important takeaway or rule of thumb. ]

---

## 10. References

These guidelines are based on analysis of the following files:
- `/content/core.typ` - Core mechanics with examples
- `/content/interference.typ` - Interference sources and solutions
- `/content/tilesets.typ` - Tileset patterns and examples
- `/content/block-event-delay.typ` - BED mechanisms
- `/content/design.typ` - Design tips and dioramas
- `/content/channels.typ` - Channel management (outline only)
- `/content/network.typ` - Network protocols (outline only)
- `/content/bulk.typ` - Bulk transport (outline only)
- `/content/data-protocols.typ` - Data protocols (outline only)
- `/lib.typ` - Library functions and callout definitions
- `/main.typ` - Main document structure