Difference between revisions of "User:Spiralofhope/documentation philosophies"

Latest revision as of 09:25, 15 June 2014

gone

@@ 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.
-: 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.