Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Reorganize to make a little more accessible, based on feedback from

YAPC::NA.
  • Loading branch information...
commit 4dba6022a1d977f170c21a4d4efb01a3d38a47bf 1 parent 000a503
Rocco Caputo authored July 30, 2011

Showing 1 changed file with 39 additions and 33 deletions. Show diff stats Hide diff stats

  1. 72  docs/TODO.otl
72  docs/TODO.otl
... ...
@@ -1,11 +1,16 @@
1 1
 [_] 40% Framework Requirements
2  
-	About
  2
+	About this Document
3 3
 		This document summarizes the best ideas from the patterns document.
4 4
 		It is also a master TODO list for Reflex.
5 5
 		It's in Vim Outliner Format.
6  
-			Basically just an outline where tab indents denote levels.
7  
-			The "[_] 0%" is ongoing progress, managed by Vim Outliner.
8  
-			http://sites.google.com/site/vimoutlinerinfo/ ... version 0.3.4 or later required.
  6
+			A plain-text outline where tabs indicate indent levels.
  7
+			Editing is easier using http://sites.google.com/site/vimoutlinerinfo/ ... version 0.3.4 or later.
  8
+			Suggestions welcome for a concise, plain-text outline format that's widely supported and software-neutral.
  9
+		Typography
  10
+			"[_]" is a checkbox denoting an incomplete to-do item.
  11
+			"[X]" denotes a completed to-do item.
  12
+			Checkboxes are followed by percentages of completion, including sub-items.
  13
+			Items without checkboxes---like the one you're currently reading---are just notes.
9 14
 		The docs/patterns.otl document tries to enumerate all available options.
10 15
 			Even ones that have been discarded.
11 16
 			Even ones we'd like to do but may never get around to.
@@ -13,35 +18,36 @@
13 18
 			Volunteers are welcome.
14 19
 		A later specification document will attempt to reconcile the requirements into a syntax and semantics.
15 20
 			This will probably become the documentation. :)
16  
-	Desirable Qualities
17  
-		Best practices should be encouraged.
18  
-			Base classes should set precedents for best practices.
19  
-			The design should encourage continued use of best practices.
20  
-		Substandard qualities should be possible but gently discouraged.
21  
-			People like to have options.
22  
-			People like to exercise those options, whether or not they're good.
23  
-			It's not the framework's duty to prevent people from doing what they want.
24  
-	Undesirable Qualities
25  
-		Avoid implicit constructs.
26  
-			Implicit constructs cause action without visible indication.
27  
-			They are disorienting.
28  
-			They interfere with comprehension.
29  
-		Avoid unnecessary magic.
30  
-			Magic is scary.
31  
-			It also implies action at a distance.
32  
-		Avoid cleverness.
33  
-			Cleverness leads to brittle design.
34  
-			It also leads to unnecessary magic.
35  
-			It also leads to implicit constructs.
36  
-		Avoid metaphors.
37  
-			Metaphors are harmful when writing abstract frameworks.
38  
-			Metaphors are useful tools for creating systems that mimic real things.
39  
-				When designed properly, metaphors provide conceptual and contextual information about a framework.
40  
-			Metaphors are contradictory to abstract design.
41  
-				Metaphors provide specific conceptual frameworks.
42  
-				System designs that fit within these frameworks are elegant.
43  
-				Systems that wish to use other concepts are generally awkward.
44  
-				Adapters can connect between metaphors, but they should not be needed.
  21
+	Project Philosophy
  22
+		Desirable Qualities
  23
+			Best practices should be encouraged.
  24
+				Base classes should set precedents for best practices.
  25
+				The design should encourage continued use of best practices.
  26
+			Substandard qualities should be possible but gently discouraged.
  27
+				People like to have options.
  28
+				People like to exercise those options, whether or not they're good.
  29
+				It's not the framework's duty to prevent people from doing what they want.
  30
+		Undesirable Qualities
  31
+			Avoid implicit constructs.
  32
+				Implicit constructs cause action without visible indication.
  33
+				They are disorienting.
  34
+				They interfere with comprehension.
  35
+			Avoid unnecessary magic.
  36
+				Magic is scary.
  37
+				It also implies action at a distance.
  38
+			Avoid cleverness.
  39
+				Cleverness leads to brittle design.
  40
+				It also leads to unnecessary magic.
  41
+				It also leads to implicit constructs.
  42
+			Avoid metaphors.
  43
+				Metaphors are harmful when writing abstract frameworks.
  44
+				Metaphors are useful tools for creating systems that mimic real things.
  45
+					When designed properly, metaphors provide conceptual and contextual information about a framework.
  46
+				Metaphors are contradictory to abstract design.
  47
+					Metaphors provide specific conceptual frameworks.
  48
+					System designs that fit within these frameworks are elegant.
  49
+					Systems that wish to use other concepts are generally awkward.
  50
+					Adapters can connect between metaphors, but they should not be needed.
45 51
 	[_] 16% Documentation Requirements
46 52
 		Many "requirements" are really recommended conventions.
47 53
 		For example:

0 notes on commit 4dba602

Please sign in to comment.
Something went wrong with that request. Please try again.