writing-docs

Writing Docs

Write CodeCompanion.nvim's docs following the Microsoft Writing Style Guide with the overrides below. Run make docs after changing any page to regenerate the vimdoc.

Voice and Tone

• Write like you speak: friendly, direct and human, aimed at Neovim users. Avoid jargon where a familiar word works.
• Lead with what matters most. Front-load keywords so readers can scan.
• Say what happens, including the edge cases: "Optional arguments can be left blank, and cancelling at any point adds nothing".
• Be brief. Cut filler words, unnecessary adverbs and phrases like "you can", "there is" and "there are" where they add nothing. Prefer one-word verbs ("try", not "attempt to").
• Avoid marketing language and hedging: no "simply", "powerful", "awesome", "seamless" or "journey".
• Start with the content. Don't open with "This guide is intended to help you..." or close with "This is useful for...".

Page Structure

• Frontmatter description: one sentence, what the page lets you do.
• The # title is "Using X" for usage pages, "Configuring X" for configuration pages and "Extending with X" for extending pages. Guides take a task title: "Running Local Models", "Choosing an Adapter".
• Open with one to three sentences: what the feature is, then how CodeCompanion does it. If the feature solves a problem, name the problem in a sentence first.
• ## then ### is the ceiling. For a sub-point under ###, use a bold line (**Images**) instead of a deeper heading.
• Section names are short nouns or gerunds: "Directories", "Groups", "Autoload", "Editing and Deleting".
• End with a "Limitations" section when there are any, stated honestly.

Code First

The rhythm is a one-line lead-in ending in a colon, then the code block:

Skills are enabled by default. To disable them:

```lua
require("codecompanion").setup({
  skills = {
    opts = {
      chat = {
        enabled = false,
      },
    },
  },
})
```

• Lead-ins: "This can be configured with:", "You can override this with:", "To set an adapter:".
• Always wrap config examples in the full require("codecompanion").setup({ ... }) nesting, so they can be pasted as-is.
• Use realistic values, not foo or bar.
• Inline comments list the allowed values or the unit, nothing more: -- Can be "default", "telescope", "fzf_lua", "mini_pick" or "snacks", -- milliseconds.
• Use ::: code-group for alternatives (Static and Conditional, Markdown and Lua) rather than two blocks with prose between them.
• Ex commands go in a bare fenced block with no language.
• Let the snippet speak for itself. Only add a sentence after it for behaviour the code can't show: "A directory further down the list takes precedence if skills of the same name clash".