tooll3--t3/.help/docs/STYLE.md

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. 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/:

  [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:

  ![SelectionRangeIndicator hovered](images/timeline-sri-hover.png)
  

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.