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.

Alternative

Supply direct links to good documentation.

Exceptions

• The upstream documentation isn't good enough.
  • Contact them, tell them how and where you looked for their documentation and what you were expecting to find.
    • Ask if you've been looking in the right place and if they have some beta documentation they've been working on.
      • 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.