User:Spiralofhope/documentation philosophies - Revision history

Spiralofhope: Replaced content with "gone"

2014-06-15T09:25:22Z

Replaced content with "gone"

Spiralofhope at 21:12, 10 May 2012

2012-05-10T21:12:55Z

Spiralofhope at 21:09, 10 May 2012

2012-05-10T21:09:06Z

Spiralofhope: 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..."

2012-05-10T21:06:19Z

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

New page

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

← Older revision		Revision as of 09:25, 15 June 2014
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.
−
−
−	~~= 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".

← Older revision		Revision as of 21:12, 10 May 2012
Line 26:		Line 26:

	* Duplicating documentation for basic commands or for common usage is ok.		* 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".

@@ Line 13: / Line 13: @@
 Avoid copying or rewriting upstream documentation.
-: Reasoning:  To do so is just extra work and a maintenance nightmare.
+; Reasoning:  To do so is just extra work and a maintenance nightmare.
-: Instead:  Supply direct links to good documentation.
+; Alternative:  Supply direct links to good documentation.
-Exceptions:
+; Exceptions:
-* The upstream documentation isn't good enough or doesn't exist.
+* The upstream documentation isn't good enough.
-** Contact them, ask if they have some beta documentation they've been working on.
+** Contact them, tell them how and where you looked for their documentation and what you were expecting to find.
-*** Perhaps you didn't know where to look for the right documentation.
+*** 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 yes:  Help their beta get finished and published.
-*** If no:  Collaborate with them.
+**** 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.
+**** 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.

User:Spiralofhope/documentation philosophies - Revision history

Spiralofhope: Replaced content with "gone"

Spiralofhope at 21:12, 10 May 2012

Spiralofhope at 21:09, 10 May 2012

Spiralofhope: 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..."

Spiralofhope: 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..."