|
|
| (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.
| |
