tixl3d--tixl
wehub-resource-sync
91 行
5.7 KiB
Markdown
91 行
5.7 KiB
Markdown
# TiXL Help — Writing Style
|
|
|
|
This directory holds **user-facing** documentation — for people making motion graphics, running live performances, writing shaders and C# operators on top of TiXL. It ships with the project and publishes to `tixl3d.github.io`.
|
|
|
|
Developer-facing docs (building TiXL from source, integration tests, CI, coding conventions, git workflow, release process) stay on the [GitHub wiki](https://github.com/tixl3d/tixl/wiki). Don't put contributor-internal topics here.
|
|
|
|
Rule of thumb: **if someone using TiXL without reading the source wants to know it, it belongs in `.help/`. If it's only relevant to someone opening `t3.sln`, it belongs in the wiki.**
|
|
|
|
## Voice and length
|
|
|
|
- Write for someone learning TiXL, not someone proving they already know it. Plain English, short sentences, second person.
|
|
- A page should answer one question or explain one feature area. If it needs a table of contents, it should probably be two pages.
|
|
- Aim for **150 – 400 lines** per page. Under 50 lines is often a sign the topic should be merged into a parent page.
|
|
- No marketing tone. No walls of warning callouts. If something is dangerous, say so once and move on.
|
|
|
|
## Structure
|
|
|
|
- **H1**: the page title (matches the filename, without the `.md`).
|
|
- **First paragraph**: one or two sentences that tell the reader what the page covers and when they'd want it.
|
|
- **H2** sections for the main beats. Use `## Heading` — no numbering, no emojis.
|
|
- **H3** only when an H2 section has internally distinct steps. Three-deep is the max.
|
|
- **Lists** when order matters (steps) or items are parallel (options). Otherwise, prose.
|
|
- End with a **See also** section linking to related pages when it helps — not because every page needs one.
|
|
|
|
## Links
|
|
|
|
- Use **relative paths** with the `.md` extension inside `.help/`:
|
|
```md
|
|
[Installation](../setup/Installation.md)
|
|
[Timeline](TimeLine.md)
|
|
```
|
|
- External links get full URLs. No bare `[text](https://...)` — introduce the link with context.
|
|
- Avoid linking the same term more than once per page.
|
|
|
|
## Images
|
|
|
|
- Store next to the page that uses them: `.help/ui/images/timeline-sri.png`.
|
|
- **Max width 1600 px**, PNG for screenshots, JPEG only for photographic content. Compress before committing — screenshots should be well under 500 KB.
|
|
- Filenames: lowercase, kebab-case, descriptive. `timeline-sri-hover.png`, not `screenshot-3.png`.
|
|
- Reference with a relative path and descriptive alt text:
|
|
```md
|
|
|
|
```
|
|
|
|
## Code and UI references
|
|
|
|
- Fenced code blocks with a language tag: ` ```csharp `, ` ```hlsl `, ` ```bash `.
|
|
- UI elements in **bold** the first time, plain after: "Press **Alt+Click** to …".
|
|
- File and class names in inline code: `` `SelectionRangeIndicator` ``.
|
|
- Keyboard shortcuts: `Ctrl+Shift+S`, not `CTRL + SHIFT + S` or `⌃⇧S`.
|
|
|
|
## Operator references
|
|
|
|
Write operator names in square brackets, e.g. `[AdjustColors]` or `[AudioReaction]`. The docs build auto-links these to the generated operator reference under `/operators/…` — no explicit link needed. Don't use inline code (`` `[AdjustColors]` ``) for them; let the auto-linker do its job.
|
|
|
|
- Prefer the **short name**. The build log warns if a short name is ambiguous and tells you the candidates.
|
|
- When ambiguous, qualify with the full path: `[Lib.numbers.float.basic.Value]`.
|
|
- For non-link mentions (discussing the word "value" conceptually, not the op), drop the brackets.
|
|
- Do not hand-edit files under `.help/operators/` — they're regenerated by TiXL from `SymbolUi.Description` and related metadata. Edit the operator description in-editor instead.
|
|
|
|
## Staying in sync with code
|
|
|
|
- **When you ship a user-visible UI or behavior change, update the matching page** in the same PR.
|
|
- If a feature is removed, remove the doc section (don't leave it marked "deprecated" indefinitely — git history is the deprecation log).
|
|
- If a page describes behavior that has drifted, **open a GitHub issue** rather than silently leaving it wrong.
|
|
|
|
## Capturing informal knowledge
|
|
|
|
Much of TiXL's knowledge lives in verbal form: Discord answers, meet-up demos, one-on-one help sessions. It's high-value and perishable — useful once, then gone.
|
|
|
|
When you answer a question, demo a feature, or help someone debug something, **ask "is anyone else likely to hit this?"** If yes, add it to the docs while it's fresh:
|
|
|
|
- A **one-paragraph FAQ entry** is better than nothing. Add it to the most relevant FAQ page or to a section's "Still to write" list with the gist in one sentence.
|
|
- A **three-minute demo on a meet-up** becomes a page (or a sub-section) in the matching area of this directory. Note the meet-up date in the commit so we can cross-reference the video later.
|
|
- A **Discord thread** can often be distilled into a single paragraph with the original question as the heading. Link back to the thread if it has extra detail.
|
|
|
|
Ten minutes of writing while the context is fresh beats an hour a week later. Small, frequent additions compound — the goal is a doc set where people can **find** answers instead of asking them for the fifth time.
|
|
|
|
If the thing you want to add doesn't have an obvious home yet, drop a note in the matching section README's "Still to write" list, or open a GitHub issue so we don't lose it.
|
|
|
|
## What not to write
|
|
|
|
- Internal implementation details (class names, private methods). Those belong in code comments or the developer wiki.
|
|
- Release notes or changelogs — those live elsewhere.
|
|
- Personal opinions, TODO lists, "I'm not sure but…". If you're not sure, don't commit the page.
|
|
|
|
## File naming
|
|
|
|
- `PascalCase.md`, matching the page title roughly. No `help.` / `dev.` / section prefixes (the folder already provides the section).
|
|
- Examples: `Introduction.md`, `UsingCustomShaders.md`, `TimeLine.md`.
|