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.

FAQs

Above all, the FAQ needs to be simple and maintainable.

If it's complex and not maintainable, then it will won't be functional at all.. and will become inaccurate.

Some basic ideas include:

• Do not mention prices. That's for resellers to list and maintain.

• Do not speculate.
  • Not even if the speculation is from an official source.

• Combine similar questions.

• Keep "questions" short.

• Remove pointless questions.
  • FAQs are supposed to answer common questions, not provide trivia or historical details. Such information can be moved elsewhere if you're anti-deletionist.

• Answer questions with a simple one-liner, and then go into detail.
  • This makes it much more simple to read.

• Remove broken wiki links.
  • And indeed I'm removing some valid links until those pages can be reviewed properly.
  • The philosophy behind good linking is to only do it when people really need to easily get to that other topic. To scatter links everywhere just because it's possible will make the FAQ intimidating.

• Remove references to "we" and "I".