From c77087f8aadc1b4973b0dd6395c5a423eab0816e Mon Sep 17 00:00:00 2001 From: Kevin Deldycke Date: Mon, 1 Nov 2021 12:12:39 +0400 Subject: [PATCH] Promote TL;DR as canonical intro. Move fancier falsehood article description to contribution guide. Refs #105 --- .github/contributing.md | 25 +++++++++++++------------ readme.md | 16 +++------------- 2 files changed, 16 insertions(+), 25 deletions(-) diff --git a/.github/contributing.md b/.github/contributing.md index 0d2e5cf..bb6522b 100644 --- a/.github/contributing.md +++ b/.github/contributing.md @@ -12,23 +12,24 @@ in this awesome list. ### Falsehood Articles -Articles following the *falsehood* scheme are prime candidates for inclusion in +Articles following the *falsehood* schema are prime candidates for inclusion in this awesome list. -These articles starts with the hypothesis that developers have a naive, simple -view of the subject at hand. Then proceed to list a set of candid assumptions -that might be held by the programmers. Each one is intentionally false, and -in their best form illustrated by a counter-example. +These articles starts with the hypothesis that developers have a naive and +simple view of a domain. Then proceed to list a set of candid assumptions that +might be held by programmers. Each one is intentionally false, and in their +best form are illustrated with a counter-example. A list of falsehood is crafted as a progression that is designed to refine concepts. Having read the whole list of falsehood, the reader should possess a -global, if not complete, overview of the domain being targeted by the article, -including most, if not all, its pitfalls, edges-cases and inconsistencies. +better overview of a domain while dispelling its myths, point out common +pitfalls and demonstrate its subtleties. -Sometimes, these kind of articles might provoke an emotional reaction and cause -flipping table. `(╯°□°)╯︵ ┻━┻` Because, the world is messy. Discovering the -complexity of a domain that is simple in appearance will lead to -frustrations. This is the sign of a great candidate for that list! +*falsehood* articles are, in a sense, a suite of wordy unit-tests covering +extensive edge-cases provided by real-world usage. The world is messy. +Discovering a domain to be much more complex than anticipated will lead to +frustrations. And cause flipping tables `(╯°□°)╯︵ ┻━┻`. This is the sign of a +great candidate for that list! Articles featuring items that are applicable to one product (or a service) and one only can't be considered as generic enough and should be avoided. @@ -36,7 +37,7 @@ one only can't be considered as generic enough and should be avoided. ### Libraries Programming libraries or modules are good candidates too, if they solve or -reduce the complexities pointed to by the *falsehood* articles above. +reduce the complexities pointed to by *falsehood* articles above. That way we can put back tables in place. `┬─┬ ノ( ゜-゜ノ)` diff --git a/readme.md b/readme.md index 27cb9b9..828421c 100644 --- a/readme.md +++ b/readme.md @@ -13,21 +13,11 @@ — Ludwig Wittgenstein[1]

-*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. +A *falsehood* is an ***idea* that you initially believe was true**, but in-reality it is **proven to be false**. -In a sense, *Falsehood* articles are a suite of wordy unit-tests covering extensive edge-cases provided by real-world usage. +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. -
- - TL;DR version (Click To Expand) - - - > A "falsehood" is an **"idea" that you initially believe was true**, but in-reality it is **proven to be false**. - > - > 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.". - > - > 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. -
+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. ## Contents