Home.md
... ...
@@ -1,18 +1,46 @@
1 1
# Tea Garden
2 2
3
-Welcome to Tea Garden, a wiki style collection of patterns curated by
4
-[Gaiwan](https://gaiwan.co). We also publish a regular newsletter where we
5
-summarize what's new on the wiki, together with some meta commentary.
3
+For some time now, we at [Gaiwan](/) have been sharing stories of the challenges
4
+we face, documenting solutions, and building up a "stack" of libraries and tools
5
+that help us get our work done. We wanted to start organizing this information
6
+and present it to a larger community. We realized that many of these things
7
+started looking like Design Patterns. So in the tradition of the original
8
+[WikiWikiWeb](https://www.c2.com) we decided to create a pattern repository that
9
+we could grow and evolve over time.
10
+
11
+Thus Tea Garden was born. Eventually, it is our goal to grow a friendly and
12
+useful garden of knowledge, something you can come and enjoy if you have a spare
13
+moment to learn a new concept, or pluck a few useful morsels from the next time
14
+you are starting a new project.
15
+
16
+We will publish a companion newsletter, _Tea Leaves_, whenever there is
17
+something of note to highlight. We will let you know when interesting new
18
+patterns appear, or alert you about existing patterns that have seen significant
19
+edits, together with commentary and insights, so you can find out what's on our
20
+mind, and why we're writing about certain patterns at a given time.
6 21
7 22
<!-- Ghost sign up form, see https://gaiwan.co/ghost/#/settings/embed-signup-form/show -->
23
+<!-- see custom.js -->
8 24
<div id="tea-leaves-sign-up-form"></div>
9 25
10
-## Navigation
26
+While this wiki is not publicly editable, we do very much want your feedback.
27
+Currently the main channel for that is the `#tea-garden` channel on [Clojurians
28
+Slack](https://clojurians.slack.com/archives/C06U8EJEXAM?ref=gaiwan.co). We
29
+welcome constructive feedback, suggested edits, new topics that you'd like to
30
+see us cover, or just any random pattern-related chat.
11 31
12
-- [[PatternOfPatterns]] - **Start Here** collection of organizational and architectural patterns and principles
32
+
33
+
34
+
35
+## Patterns
36
+
37
+- [[PatternLanguage]] - **Start Here** collection of organizational and architectural patterns and principles
13 38
- [[UriAsData]] - Recommends managing URIs as structured data for reliability.
14 39
- [[DevEnvironmentLauncher]] - Simplifies and standardizes development setup for consistency and efficiency.
15 40
41
+## Ecosystem
42
+
43
+- [[DevEnvironmentLauncherEcosystem]]
16 44
17 45
<<Navigation("Gaiwan Stack", "GaiwanStack", false)>>
18 46
PatternLanguage.md
... ...
@@ -0,0 +1,100 @@
1
+## Introduction
2
+
3
+This wiki documents _a_ pattern language, the language used by the [Gaiwan](/) team.
4
+
5
+The concept of a Pattern Language was proposed by Christopher Alexander, an
6
+architect and design theorist active in the second half of the 20th century, in
7
+a sequence of three books. This influenced a design patterns movement within
8
+Software Development, kick-started by the book *Design Patterns: Elements of
9
+Reusable Object-Oriented Software (1994)*.
10
+
11
+This book has had an outsized impact on Software Development practice and
12
+discourse, and has shaped the general understanding of what design patterns are
13
+and how they apply to developing, deploying, and maintaining software.
14
+
15
+## What is a Pattern?
16
+
17
+If you have been around in software for a while, you likely have a number of
18
+preconceived notion of what a "design pattern" does or doesn't looks like. For
19
+this wiki we take a broad look, inspired by Alexander formulation of pattern
20
+forming a _language_.
21
+
22
+Here are some common conceptions we don't subscribe to:
23
+
24
+- Design patterns are mainly about objects and classes (not true, at any level
25
+ of system design and development, and in any flavor programming, patterns
26
+ occur)
27
+- "Design pattern" refers specifically to one of the patterns in the book (not
28
+ true, many more patterns have been described, and many more exist but have not
29
+ formally been described)
30
+- Only in specific cases do you use a design pattern, the rest is just "regular
31
+ code" (not true, if you look closely you will find patterns implicitly in
32
+ almost all the code you write or systems you build, fractally)
33
+- Patterns have a typical size, somewhere between a few and a few dozen objects
34
+ (not true, patterns are in fact fractal, meaning most patterns form a
35
+ combination of smaller patterns, and are themselves components in bigger
36
+ patterns)
37
+- Once a pattern has been formally described it is set in stone, and unless an
38
+ implementation follows the description to the letter, it can not be seen as an
39
+ implementation of said pattern (Patterns form a language, and language evolves
40
+ to adapt to a changing world)
41
+- A pattern description has to follow the formal template used in the Design
42
+ Pattern book (It's good to have a template and common organization, but we
43
+ don't want that to hold us back from describing and publishing patterns we
44
+ see.)
45
+
46
+## A Pattern Language
47
+
48
+In terms of the source material, the most commonly referenced of Alexander's
49
+books is *A Pattern Language* (1977), which describes a specific set of patterns
50
+which Alexander and his collaborators found to be a useful and sufficient
51
+language for building. However, to truly understand the intent and scope of
52
+design patterns we have to read *The Timeless Way of Building* (1979), which was
53
+published a few years later, but which Alexander saw as the predecessor of *A
54
+Pattern Language*, setting the stage and explaining his philosophy and intent.
55
+This is the source material that we go back to for our conceptualization of A
56
+Pattern Language.
57
+
58
+It is important to note that a Pattern Language is a language, an idiom, which
59
+shares many characteristics with natural language.
60
+
61
+- It is shared by a group of people, which use it daily as a means of
62
+ communication, and as a basis for developing and expressing ideas
63
+- Different but adjacent groups will often speak similar (overlapping) but
64
+ distinct languages
65
+- Each person uses the language slightly differently
66
+- Language evolves over time, it grows and changes, meanings evolve
67
+- A word's meaning is its usage (this is descriptivist rather than
68
+ prescriptivist view of language, which we subscribe to)
69
+
70
+Much like natural languages, a pattern language may evolve over time as it grows
71
+and changes and meanings shift. A word's meaning is its usage (this is
72
+descriptivist, rather than prescriptivist, view of language with which we
73
+agree), and so too with a pattern: how it is used determines what it means
74
+beyond any prescribed definition.
75
+
76
+The pattern language described in the **Tea Garden** is the language spoken by
77
+the Gaiwan team, our common vernacular. The patterns in our pattern language can
78
+extend from the very small (tiny programming language idioms) to the very large
79
+(deployment and maintenance of entire systems), and even beyond the purely
80
+technical to organizational and social patterns. We describe patterns wherever
81
+we see them and find them useful and hope that, by sharing them here, others can
82
+benefit from the growth and evolution of our pattern language.
83
+
84
+## Conclusion
85
+
86
+For Alexander, a Pattern describes a set of relationships between building or
87
+environmental elements that, when followed, help to resolve tensions and inner
88
+contradictions that exist within the larger system. This is a very useful
89
+framing. Much of the software pattern literature talks about "forces" rather
90
+than "tensions". We prefer "tension", since this is also what one feels while
91
+working on these systems. Trying to combine elements in software design is not
92
+always straightforward. The software pushes back. It creates tension, and we as
93
+developers and architects feel that tension within us. A good pattern will allow
94
+us to resolve these tensions, and when we reach that point we will literally
95
+experience a feeling of resolution and release.
96
+
97
+By applying these patterns, and resolving these tensions, we can hope to
98
+approach a Timeless Way of Building Software. Software that is imbued with the
99
+quality without a name. Alive, whole, elegant, precise, ego-less, eternal, free
100
+from inner contradictions.
PatternOfPatterns.md
... ...
@@ -1,50 +1,27 @@
1
-## Introduction
2
-
3
-The concept of a Pattern Language was proposed by Christopher Alexander, an architect and design theorist active in the second half of the 20th century, in a sequence of three books. This influenced a design patterns movement within Software Development, kick-started by the book *Design Patterns: Elements of Reusable Object-Oriented Software (1994)* (colloquially known as the "Gang of Four" book). This book has had an out-sized impact on Software Development practice and discourse, and has shaped the general understanding of what design patterns are and how they apply to developing, deploying, and maintaining software.
4
-
5
-
6
-## What is a Pattern?
7
-
8
-As with any concept, such as Design Patterns, that has been around for a long while, interpreted and re-interpreted by many groups and individuals over the years, it is instructive to start by stating what Design Patterns are *not*:
9
-
10
-* Design patterns are *not* mainly about objects and classes
11
-* "Design pattern" does *not* refer specifically to one of the patterns in the book
12
-* A Design Pattern is *not* something you only use in specific cases (with the rest of what a programmer writes being just "regular code" )
13
-* Design Patterns are do *not* have a set size range
14
-* A Design Pattern is *not* something that is rigid and set in stone, such that every implementation must follow every detail of the pattern to the letter
15
-* The description of a Design Pattern does *not* have to follow the formal template used in the Design Pattern book
16
-
17
-So, if Design Patterns are not any of these things, then what are they?
18
-
19
-Patterns can exist at any level of system design or development, in any flavor of programming language or approach. There are many patterns beyond those described in any single book. Indeed, new patterns will naturally arise all the time as new problems are approached by developers in new and inventive ways. If you look closely, you will find patterns exist implicitly in almost all the code you write or systems you build. Furthermore, patterns are often fractal, meaning most patterns form a combination of smaller patterns, and are themselves components in bigger patterns. Finally, and perhaps most importantly, Design Patterns form a language that constantly evolves to adapt to a changing world.
20
-
21
-
22
-## A Pattern Language
23
-
24
-In terms of the source material, the most commonly referenced of Alexander's books is *A Pattern Language* (1977), which describes a concrete set of patterns which Alexander and his collaborators found to be a useful and sufficient language for building. However, to truly understand the intent and scope of design patterns we have to read *The Timeless Way of Building* (1979), which was published a few years later, but which Alexander saw as the predecessor of A Pattern Language, setting the stage and explaining his philosophy and intent. This is the source material that we go back to for our conceptualization of A Pattern Language.
25
-
26
-It is important to note that a Pattern Language is a language, an idiom, which shares many characteristics with natural language. It is shared by a group of people who use it daily as a means of communication. It forms a basis for developing and expressing ideas. Different, but adjacent, groups will often speak similar, overlapping but distinct pattern languages, and each person will use that language in their own unique way.
27
-
28
-Much like natural languages, a pattern language may evolve over time as it grows and changes and meanings shift. A word's meaning is its usage (this is descriptivist, rather than prescriptivist, view of language with which we agree), and so too with a pattern: how it is used determines what it means beyond any prescribed definition.
29
-
30
-The pattern language described in the **Tea Garden** is the language spoken by the Gaiwan team, our common vernacular. The patterns in our pattern language can extend from the very small (tiny programming language idioms) to the very large (deployment and maintenance of entire systems), and even beyond the purely technical to organizational and social patterns. We describe patterns wherever we see them and find them useful and hope that, by sharing them here, others can benefit from the growth and evolution of our pattern language.
31 1
32 2
33 3
## The Pattern of Patterns
34 4
35
-When it is time to start a new project, or a major new feature of an existing project, there are typically many technical decisions that need to be made. How you approach these decisions, and how you evaluate the patterns you choose for crafting a solution, forms a pattern in and of itself. We call this the "Pattern of Patterns", and the patterns that you will find in the **Tea Garden** will, for the most part, follow this pattern. In a sense, this pattern forms the foundation upon which we hope to build the **Tea Garden**'s Pattern Language.
5
+When it is time to start a new project, or a major new feature of an existing
6
+project, there are typically many technical decisions that need to be made. How
7
+you approach these decisions, and how you evaluate the patterns you choose for
8
+crafting a solution, forms a pattern in and of itself. We call this the "Pattern
9
+of Patterns", and the patterns that you will find in the **Tea Garden** will,
10
+for the most part, follow this pattern. In a sense, this pattern forms the
11
+foundation upon which we hope to build the **Tea Garden**'s Pattern Language.
36 12
37
-So what is the "Pattern of Patterns"? We have found that approaching a new way of doing things (a new "Pattern", if you will) generally proceeds through 4 phases:
13
+So what is the "Pattern of Patterns"? We have found that approaching a new way
14
+of doing things (a new "Pattern", if you will) generally proceeds through 4
15
+phases:
38 16
39 17
1. High-Level Evaluation
40 18
2. Narrowing of Candidate Approaches
41 19
3. Adoption
42 20
4. Dealing with the Consequences
43 21
44
-Within the Tea Garden project, we explore an array of patterns, presenting each with a concise overview, a comparison of possible approaches with a focus on Gaiwan's choice, and a discussion on common challenges with solutions. This structured exploration aims to equip users with the necessary insights to effectively implement these patterns, and hopefully elevate their software development practices.
45
-
46
-## Conclusion
47
-
48
-For Alexander, a Pattern describes a set of relationships between building or environmental elements that, when followed, help to resolve tensions and inner contradictions that exist within the larger system. This is a very useful framing. Much of the software pattern literature talks about "forces" rather than "tensions". We prefer "tension", since this is also what one feels while working on these systems. Trying to combine elements in software design is not always straightforward. The software pushes back. It creates tension, and we as developers and architects feel that tension within us. A good pattern will allow us to resolve these tensions, and when we reach that point we will literally experience a feeling of resolution and release.
49
-
50
-By applying these patterns, and resolving these tensions, we can hope to approach a Timeless Way of Building Software. Software that is imbued with the quality without a name. Alive, whole, elegant, precise, ego-less, eternal, free from inner contradictions.
22
+Within the Tea Garden project, we explore an array of patterns, presenting each
23
+with a concise overview, a comparison of possible approaches with a focus on
24
+Gaiwan's choice, and a discussion on common challenges with solutions. This
25
+structured exploration aims to equip users with the necessary insights to
26
+effectively implement these patterns, and hopefully elevate their software
27
+development practices.
_Footer.md
... ...
@@ -0,0 +1 @@
1
+_You are reading [Tea Garden](/wiki), a wiki-style pattern repository by [Gaiwan](/). Sign up for [the newsletter](/blog) to stay up to date about new developments._