Roam Product Writing

Roam product writing

Explain why Roam belongs in a coding agent's tools, not just what features it contains. An accurate sentence can still present the wrong product. Earn a strong claim with concrete work and a supported mechanism, not adjectives.

Choose by the passage's job, not its file extension. Product explanation belongs here; technical instructions for an acting agent need instruction/contract review, and a new comparative benefit claim needs qualified measurement. A mixed page can need both kinds of work without turning its explanation into an operating manual.

Establish meaning and authority

Read the source map and the sources relevant to the surface. Resolve the Roam checkout from context; a supplied frozen source packet can replace repository reads in isolated trials. Treat current copy as editing input, not its own factual proof. Cite source locations in separate working notes.

Latest explicit owner direction sets positioning; verified implementation bounds capability; adopted records govern commercial terms. Older headlines are not templates to restore. Distinguish working-tree, published, planned, and measured behavior. Name a contradiction or unavailable fact; do not silently select the convenient source. Keep private strategy and customer information out of public copy. Package descriptions and registry cards are public copy too; a bounded website claim does not repair an absolute claim in metadata.

Match evidence to the claim: implementation supports capability, the license supports licensing, owner decisions govern offers, and measurements support outcome comparisons. Missing one source is a specific gap, not grounds to reject every supported part of a sentence.

Use the orientation's The product model behind the words as the maintained meaning, not a stock tagline. Roam gives coding agents callable local analysis and mechanical checks for investigating code, evaluating implementation choices, and checking changes. Context, findings, algorithmic alternatives and scoped verification evidence are useful outputs, not competing definitions of the product. Some evidence comes from fixed experiments or replay, not just the code graph. Do not reduce Roam to code understanding, a bug finder, or a post-edit reviewer. The public atlas is an illustration for visitors, not the agent's working interface.

People choose tools and set direction; agents consume results. Generated code can outpace line-by-line attention. Roam's value is making useful repository questions mechanically answerable and repeatable, not declaring human reading obsolete or the model incapable. Do not advertise a self-improving system or perfect understanding. The agent reasons about applicability and directs work; Roam returns observations and performs supported requested operations. Candidate improvements are not implemented solutions or demonstrated speedups.

For substantive positioning work, first record a short private meaning brief: the reader and their task, what Roam supplies, what the agent does with it, why the mechanism is worth adding, and which evidence bounds the claim. This is reasoning input, not a template to paste into every surface. Reading the docs is not proof of understanding: check a mechanism beyond the opening example and ask what remains useful when no defect is found. Resolve conflicting current guidance rather than allowing the next page to inherit the same contradiction.

Build a useful explanation

Identify the reader's question and the section's job before drafting. For an opening, make the purpose recognizable and show why the supplied context/checks matter to real work. For a capability card, connect a named output to its use. For a FAQ, answer the practical objection and provide the next step.

In an opening, answer the reason to add Roam to an agent the reader already uses. A category plus a feature list is not that answer. Explain useful work and the mechanism that supplies it: query code relationships, inspect a pattern and a candidate alternative, or obtain a recorded check result. Ready-to-query analysis and executable checks let an agent consult results instead of deriving each relationship or building each check anew. This is a mechanism, not a measured saving or a claim that the existing agent cannot investigate code. Choose a hook suited to the reader; neither a fixed verb trio nor one concrete example should become the entire product identity.

Test the opening by paraphrasing only its visible words: what Roam supplies, how it obtains that result, and what the existing agent can do with it. A list of agent jobs (understand, find problems, improve, check) does not explain the added tool. If the same opening could describe the coding agent itself, name Roam's contribution instead of adding another benefit verb. This is a test of the explanation, not a requirement for a unique competitive feature or a fixed slogan. The headline sets the category or useful task; the lede must supply the reason to add Roam without relying on a diagram or lower section.

Explain labels such as "context" through a useful output and next action. Check a healthy-code case: what useful answer remains when no problem is found? Reuse means an index or checked observation can serve later questions under refresh conditions, not measured savings or automatic freshness. Put refresh instructions in the workflow unless the opening implies reuse across changed source; qualify that stronger claim immediately. Do not spend every opening on setup.

Prefer files, functions, connections, duplicate code, tests, and checks to an unexplained catalogue of technical categories. Keep necessary technical meaning. When shortening, preserve a named output and how Roam obtains it. "Engineering checks" or "candidate algorithms" alone can still hide the work: indexed callers, a detected source pattern paired with a catalogued alternative, or a replay result are more concrete when supported by the relevant source. Describe the producer accurately rather than implying model-generated proposals. For an adoption introduction, make the local, model-free nature of static checks legible; "mechanical" is not a substitute for explaining it. Keep connected-model usage separate. These are meaning checks, not required phrases in every section. Use confident verbs for supported behavior and conditional wording for uncertain inferences. Do not hedge every sentence. Stronger copy adds a specific result, use, or mechanism; it does not need a larger promise. "Local graph + judgment + evidence" may name internal concepts but does not explain a benefit to a visitor. "Deterministic facts, not guesses" confuses repeatable analysis with certainty.

Read entry copy aloud as if explaining Roam to a developer over a desk. Replace internal labels with the work they describe: a reader should not need to decode “clone evidence” to learn that similar code may need attention. Let the headline establish a recognizable category or invite a concrete task, and let the lede explain the mechanism; neither has to carry the whole product manual. Keep precise terms in technical references where the audience needs them. Use a nearby, clearly labelled example to show a useful question and returned result; a list of check categories cannot do that job. Name what a broad phrase such as “structural concerns” means in that example. Preserve the stronger baseline passage when a warmer rewrite obscures the agent's next action.

Keep the actor clear in every instruction: is a person connecting the tools, the agent consulting them, or Roam returning a result? Do not turn the agent-first story into a list of manual chores. Give adjacent sections different explanatory jobs; consistency is shared meaning, not repeating the same words everywhere. An algorithm page can focus on candidate alternatives; a README introduction needs the wider purpose; a paid offer sells its actual deliverable, not free tooling relabelled as a subscription. Lead with useful work, attach the relevant limit, and preserve agreed commercial terms. A focused page need not repeat the whole capability range to be consistent.