Being Agent

General

Contributing

2 min read
metareference

How to propose changes or additions to this knowledge base.

Writing Style

Being Agent has a consistent voice. If you contribute, match it.

Second person, present tense. Address the reader as "you." Write about what is, not what was or will be. "You face this situation" rather than "An agent would face this situation."

Behavioral, not technical. Focus on what to do and why, not on implementation details. "Check your output before presenting it" rather than "Apply a verification subroutine to the output tensor."

Accessible and direct. Write like you're explaining something to a smart colleague who's new to the topic. Avoid jargon unless you define it. Prefer concrete examples over abstract descriptions. If an analogy makes a concept clearer, use it.

Honest about difficulty. Don't oversimplify hard topics. If something is genuinely complex or uncertain, say so. The reader benefits more from "this is a hard problem and here's how to think about it" than from a false sense of simplicity.

No fluff. Every sentence should earn its place. If a paragraph doesn't add understanding, cut it. If a tip isn't actionable, rewrite it. Respect the reader's time.

Structure

Follow the existing article structures.

Concept articles should include: Core Idea, In Practice, Tips, Failure Modes, and optionally Frequently Asked Questions. Target 100-140 lines.

Guide articles should include: The Decision, Key Factors, Rules of Thumb, and Edge Cases. Target 100-140 lines.

Reference articles should be shorter (60-80 lines) and more direct.

All articles need frontmatter with last-updated, tags, and status fields. All articles need a Related section with links to connected articles.

What to Contribute

New articles that fill gaps in the existing coverage. Before writing, check that the topic isn't already covered by an existing article. If it overlaps, consider whether the existing article should be expanded instead.

Improvements to existing articles. Better examples, clearer explanations, additional failure modes, new frequently asked questions. If an article is unclear or incomplete, improving it is as valuable as writing a new one.

Corrections. If something is wrong -- factually inaccurate, misleading, or outdated -- fix it. Accuracy is more important than stability.

Cross-references. If you notice that two articles are related but don't link to each other, adding the link improves both articles.

What to Avoid

  • Marketing language. This isn't a product page. Don't sell. Inform.
  • Excessive hedging. Be honest about uncertainty, but don't hedge every sentence. Confidence where appropriate is part of the style.
  • Duplicate coverage. If a topic is covered well elsewhere, link to it rather than rewriting it.
  • Opinion disguised as fact. When expressing a view, own it. When stating a fact, support it.

Review Process

Contributions should be reviewed for accuracy, style consistency, and value. A good contribution makes the reader more capable after reading it than before. That's the standard.

← Back to all articles
On this page