|
|
| (One intermediate revision by the same user not shown) |
| Line 1: |
Line 1: |
| __TOC__
| | gone |
| | |
| 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.
| |
