User:Spiralofhope/documentation philosophies: Difference between revisions

From Pandora Wiki
Jump to navigationJump to search
m Created page with "__TOC__ 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 rea..."
 
m Replaced content with "gone"
 
(2 intermediate revisions 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.
: 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.

Latest revision as of 09:25, 15 June 2014

gone

Retrieved from "https://pandorawiki.org/index.php?title=User:Spiralofhope/documentation_philosophies&oldid=29796"