Skip to content

Commit c77087f

Browse files
committed
Promote TL;DR as canonical intro.
Move fancier falsehood article description to contribution guide. Refs #105
1 parent b5dcc80 commit c77087f

File tree

2 files changed

+18
-27
lines changed

2 files changed

+18
-27
lines changed

.github/contributing.md

+13-12
Original file line numberDiff line numberDiff line change
@@ -12,31 +12,32 @@ in this awesome list.
1212

1313
### Falsehood Articles
1414

15-
Articles following the *falsehood* scheme are prime candidates for inclusion in
15+
Articles following the *falsehood* schema are prime candidates for inclusion in
1616
this awesome list.
1717

18-
These articles starts with the hypothesis that developers have a naive, simple
19-
view of the subject at hand. Then proceed to list a set of candid assumptions
20-
that might be held by the programmers. Each one is intentionally false, and
21-
in their best form illustrated by a counter-example.
18+
These articles starts with the hypothesis that developers have a naive and
19+
simple view of a domain. Then proceed to list a set of candid assumptions that
20+
might be held by programmers. Each one is intentionally false, and in their
21+
best form are illustrated with a counter-example.
2222

2323
A list of falsehood is crafted as a progression that is designed to refine
2424
concepts. Having read the whole list of falsehood, the reader should possess a
25-
global, if not complete, overview of the domain being targeted by the article,
26-
including most, if not all, its pitfalls, edges-cases and inconsistencies.
25+
better overview of a domain while dispelling its myths, point out common
26+
pitfalls and demonstrate its subtleties.
2727

28-
Sometimes, these kind of articles might provoke an emotional reaction and cause
29-
flipping table. `(╯°□°)╯︵ ┻━┻` Because, the world is messy. Discovering the
30-
complexity of a domain that is simple in appearance will lead to
31-
frustrations. This is the sign of a great candidate for that list!
28+
*falsehood* articles are, in a sense, a suite of wordy unit-tests covering
29+
extensive edge-cases provided by real-world usage. The world is messy.
30+
Discovering a domain to be much more complex than anticipated will lead to
31+
frustrations. And cause flipping tables `(╯°□°)╯︵ ┻━┻`. This is the sign of a
32+
great candidate for that list!
3233

3334
Articles featuring items that are applicable to one product (or a service) and
3435
one only can't be considered as generic enough and should be avoided.
3536

3637
### Libraries
3738

3839
Programming libraries or modules are good candidates too, if they solve or
39-
reduce the complexities pointed to by the *falsehood* articles above.
40+
reduce the complexities pointed to by *falsehood* articles above.
4041

4142
That way we can put back tables in place. `┬─┬ ノ( ゜-゜ノ)`
4243

readme.md

+5-15
Original file line numberDiff line numberDiff line change
@@ -13,21 +13,11 @@
1313
— Ludwig Wittgenstein<sup id="intro-quote-ref"><a href="#intro-quote-def">[1]</a></sup>
1414
</p>
1515

16-
*Falsehood* articles are a form of commentary on a particular subject, and are appreciated by the developer community at large for their effectiveness and terseness. They're a convenient written form to approach an unfamiliar domain by dispelling myths, point out common pitfalls, show inconsistencies and subtleties.
17-
18-
In a sense, *Falsehood* articles are a suite of wordy unit-tests covering extensive edge-cases provided by real-world usage.
19-
20-
<details>
21-
<summary>
22-
<strong>TL;DR version</strong> <sub>(Click To Expand)</sub>
23-
</summary>
24-
25-
> A "falsehood" is an **"idea" that you initially believe was true**, but in-reality it is **proven to be false**.
26-
>
27-
> E.g. "**Idea:** Valid email address exactly has one `@` character, right? I will use this rule to implement my email-field validation logic. **Reality:** False! Emails [can have multiple `@` chars](#emails), therefore my implementation should allow this.".
28-
>
29-
> These listed articles will have a comprehensive list of those false-beliefs that you should be aware of, to help you become a better programmer.
30-
</details>
16+
A *falsehood* is an ***idea* that you initially believe was true**, but in-reality it is **proven to be false**.
17+
18+
E.g. of an *idea*: valid email address exactly has one `@` character. So, you will use this rule to implement your email-field validation logic. Right? Wrong! The *reality* is: emails [can have multiple `@` chars](#emails). Therefore youy implementation should allow this. The initial *idea* is the a falsehood you believed in.
19+
20+
The *falsehood* articles listed below will have a comprehensive list of those false-beliefs that you should be aware of, to help you become a better programmer.
3121

3222
## Contents
3323

0 commit comments

Comments
 (0)