patrykandpatrick Docs
Guide prose rules
When editing Vico guide prose:
- Link first mentions on each page. The first mention of a code element should link to the API reference.
- Avoid nounifying code names. Do not use code element names as generic count
nouns, such as “a
Foo,” “theBar,” or plural forms like “Bazs.” Attach articles to generic nouns instead, such as “aFooinstance.” - Distinguish classes from instances. If prose refers to an object, say “instance” or use a generic noun such as “chart,” “model,” “layer,” “marker,” or “transaction.” Introduce the code element name separately when needed.
- Prefer generic nouns for concepts. Use ordinary language for the concept under discussion, and reserve code names for precise API references.
- Keep terminology parallel. In comparisons and lists, phrase equivalent ideas symmetrically.
Editing workflow
- Identify the target guide page or documentation copy.
- Make the requested prose changes, keeping the surrounding terminology and API references consistent.
- Check first mentions of code elements after edits, because moved or rewritten text can change which mention is first on the page.
- Review the edited paragraphs for code-name nounification and class–instance ambiguity before finishing.