Documentation

Write Labtasker documentation

Write for an ML researcher or engineer who has independent inference, evaluation, or experiment jobs but has never used Labtasker. The reader may not know task-queue terminology. Help them understand what Labtasker is within one sentence, recognize its main benefits within one short section, and decide whether to use it before teaching the internal model.

Put definition and value first

The README and documentation homepage should follow this reader journey:

1. One direct sentence defining Labtasker.
2. Prominent links to the documentation, llms.txt, and source code.
3. A short paragraph explaining what Labtasker adds to existing ML code.
4. Three to five consolidated key features.
5. Installation and a short representative example.
6. Separate When to use Labtasker and When NOT to use Labtasker sections.
7. Navigation to tutorials, concepts, guides, and reference pages.

Do not begin with a long hypothetical workload, implementation details, v1 history, or internal terminology. Put fuller motivation and v1-to-v2 rationale in docs/why-labtasker.md.

Keep the README and documentation homepage aligned on the definition, features, and product boundary. The README may contain a compact example; the homepage should focus on navigation after establishing the product.

Write features as claims with evidence

Use the SQLModel-style pattern **Short benefit:** Concrete explanation. A positive adjective such as effortless is useful when the following sentence immediately demonstrates why it is true.

Consolidate related capabilities instead of listing every mechanism separately. The current product story fits four groups:

• effortless and flexible parallelism;
• resumable and failure-resistant experiments, supported by tested lifecycle behavior;
• structured Task records for inspection; and
• easy adoption and use, including end-to-end operation by agents.

Prefer user-visible capabilities such as automatic retry, dynamic priority, cancellation, recorded results, and agent operation. Do not lead with SQLite, local daemon startup, dependency separation, leases, or run_id fencing. Those details belong where readers configure or verify the behavior.

Do not narrow the entire product to one incidental condition such as uneven runtimes or one benchmark type. Concrete scenarios are useful examples, not the definition of Labtasker's scope.

Use direct, natural language

Use short sentences that say what the reader can do. Prefer familiar ML words such as jobs, cases, GPUs, failures, results, and restart before introducing Task, Worker, Queue, route, attempt, lease, or run_id.

Avoid infrastructure metaphors and compressed abstractions on landing pages:

• Write “resume after an interruption without rerunning completed jobs,” not “jobs survive interruption.”
• Write “when a Worker stops responding,” not “abandoned Tasks.”
• Write “matching Task,” not “eligible Task,” until matching rules are taught.
• Write “results from old runs,” not “stale results,” until run_id is taught.
• Write “a simple loop can be sufficient,” not “a simple loop is better.”

Avoid vague words such as consistent, robust, advanced, powerful, or easy unless the same item gives a concrete reason. Do not use em dashes; split the thought into shorter sentences or use commas, parentheses, or a colon.

Prefer plain English over idioms, metaphors, and colloquial shortcuts. Write “this example uses addition to demonstrate the workflow,” not “addition stands in for inference.” Write “Workers take Tasks from the same Queue,” not “Workers draw from the backlog.” A reader should not need to interpret a turn of phrase before understanding the product behavior.

Use Labtasker terminology consistently and capitalize public concepts: Task, Queue, Worker, Client, and Server. Use lowercase route because it is a label, not a resource record.

Wording blacklist

Never use these phrases or close variants in user-facing documentation:

• provide the compute, supplies the compute, or compute you control.

These phrases sound like infrastructure-provider language and obscure the actual product boundary. When that boundary matters, state the concrete fact, such as “Labtasker does not allocate GPUs or start machines” or “You start the Worker processes.” Do not replace a blacklisted phrase with a synonym that has the same problem.

Before handing off a documentation change, search every changed user-facing file for the listed phrases and read the changed prose once for close variants. Rewrite every match in terms of the specific action or boundary that matters.

Treat explicit user feedback as an input to this blacklist. When a user says they dislike a type of wording and that wording is common enough to recur in Labtasker documentation, update the blacklist as part of the same task. Record the general pattern rather than only the sentence that triggered the feedback, explain why it should be avoided, and give concrete rewriting guidance. Follow one-off or context-specific wording preferences in the current edit, but do not turn them into a repository-wide rule unless they describe a recurring pattern.

Explain why before how

Navigation and page order should let readers decide whether Labtasker applies before asking them to learn its model. Put Why Labtasker? before How Labtasker works.

Use one primary Diataxis type per page:

• tutorials lead the reader through a complete successful workflow;
• guides solve one concrete task;
• concepts explain the model and design decisions;
• references state exact interfaces and constraints with minimal prose.

Do not create a top-level navigation group for one page. Do not expose internal concepts as unexplained top-level categories. Worker pages belong with guides; a single development page should be linked directly.

Make tutorials demonstrate the queue

A first tutorial should submit multiple cases to one Queue, run them through a Worker, and verify all recorded results. A single case does not demonstrate why a queue is useful.

Keep the first tutorial copyable and dependency-free. Use a small evaluation program that resembles an ML workflow, then link to representative inference or benchmark examples. State prerequisites before commands and make successful output recognizable.

When a tutorial first introduces a route, choose a label that looks like the workload or compatible implementation, such as robotwin, libero, or sdxl-diffusers. The submitted Tasks and Worker must use the same route.

Keep maintained examples in concise source files and include them with --8<-- when the same example is tested. Do not display an entire long implementation when a short excerpt proves the point.

Comment only the parts of an example that the reader must replace or understand to adapt it. Do not add comments that restate every line. When real model loading, inference, evaluation, or project configuration is intentionally omitted, mark that location explicitly with a short # TODO: Replace ... comment. Fully runnable tutorial code should not contain placeholder TODOs.

Describe product boundaries explicitly

Use separate When to use Labtasker and When NOT to use Labtasker sections. Acknowledge that a simple loop can be sufficient for a small experiment with a few short jobs that can be rerun in full.

State the boundaries through alternatives:

• use a workflow or DAG system when jobs depend on earlier outputs;
• use a cluster or resource scheduler to allocate GPUs or machines;
• use an artifact store for checkpoints, media, and other large outputs.

Labtasker schedules independent Tasks. Users provide and start the processes that run them. Keep this boundary visible without interrupting the opening with implementation responsibility.

Explain the agent advantage precisely

Labtasker's API, non-interactive CLI, bundled Agent Skill, llms.txt, and raw Markdown documentation allow Labtasker operations to be handed to an agent end to end. Describe concrete operations: Worker setup, submission, inspection, priority changes, cancellation, and recovery.

Do not imply that the agent defines the experiment, allocates hardware, or must remain online while a Worker executes a Task. The researcher still defines the experiment, and Labtasker does not allocate hardware.

Keep docs/llms.txt as a concise, curated map. Put Why Labtasker? before the core model and update the map when a primary entry point moves or changes role.

Use Mermaid only when relationships need it

Use Mermaid for a lifecycle, component relationship, or multi-step flow when it is materially clearer than prose or a small table. Good candidates include:

• Client, Server, Queue, and Worker relationships;
• Task state transitions;
• claim, heartbeat, retry, and recovery sequences; and
• choosing between Python, command, and distributed Workers.

Do not add a diagram for a single fact, a short list, or a linear procedure that is already clear. Keep node labels short, use public terminology, and introduce the diagram with enough prose for the surrounding section to remain useful when retrieved without the image. Prefer Mermaid over a new bitmap for maintainable technical diagrams.

Use comparisons and case studies selectively

Do not put a without/with comparison table on the landing page by default. Use one only when it adds information beyond the feature list, normally in Why Labtasker?.

A comparison must explain both method and consequence. Do not write a bare pair such as “static assignment / dynamic claiming.” Explain what the researcher does, where it becomes costly, what Labtasker changes, and why that matters.

Use representative case studies such as AIGC generation, ablations, or Embodied-AI evaluation. A case study should identify the original workload, show the coordination code the project owned, map each independent case to a Task, and state what remains outside Labtasker. Treat external projects respectfully and link important claims to stable primary sources.

Describe v2 as a design change

When comparing v1 and v2, discuss product decisions rather than renamed flags:

• one complete way to perform each operation;
• explicit route matching;
• defined lifecycle, recovery, and run_id protection;
• deterministic interfaces for humans and agents;
• a Python-native local experience; and
• explicit HTTP deployment only when machines share work.

Do not make v1 implementation differences primary product features. Do not frame extensibility itself as a mistake.

Control length and verify claims

Give each section one job. Remove repeated motivation, technical qualifications, and examples that do not change a decision or prevent an error. Prefer a short paragraph, a compact table, or a small code excerpt over all three.

Before handoff, check every new claim:

1. Verify Labtasker behavior against docs/reference/specification.md, code, configuration, and tests.
2. Verify external claims against stable primary sources.
3. Remove facts that are accurate but distract from the user's decision or task.
4. Read the result as a new ML researcher and replace technical shorthand with direct outcomes.
5. Confirm that a quoted section contains enough context for agent retrieval.
6. Check every changed user-facing file against the wording blacklist and rewrite exact matches or close variants.

If observable behavior changes, also use the public-contract-change skill and update the complete public slice. Preserve unrelated worktree changes and never hand-edit generated site/.

For ambiguous positioning or structure work, discuss two to five high-leverage questions per round. Once the direction is clear, update all affected surfaces, run uv run zensical build --clean, check links, and run examples or focused tests that support new claims. Documentation-only changes do not require unrelated runtime tests.