User:Spiralofhope/documentation philosophies

This is a combination FAQ, rant, statement of intent, (what's the other good word)..

It'll eventually get moved to my own site, but I'll build it here so people can read it and understand my reasonings.

1. Maintainability

Over everything else, documentation must be maintainable.

1.a. Avoid duplication

Avoid copying or rewriting upstream documentation.

Reasoning: To do so is just extra work and a maintenance nightmare.

Instead: Supply direct links to good documentation.

Exceptions:

• The upstream documentation isn't good enough or doesn't exist.
  • Contact them, ask if they have some beta documentation they've been working on.
    • Perhaps you didn't know where to look for the right documentation.
    • If yes: Help their beta get finished and published.
    • If no: Collaborate with them.
    • If they aren't amenable to collaboration, do it yourself and publish it here. Use it as leverage to make fun of their bad documentation.

• Duplicating documentation for basic commands or for common usage is ok.