You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -22,20 +22,19 @@ This repository has reached an equilibrium state. We are past its accumulation p
22
22
23
23
## Linting
24
24
25
-
Have your pull-request pass the [official Awesome List's linter](https://github.com/sindresorhus/awesome-lint).
25
+
Your pull-request should pass the [official Awesome List's linter](https://github.com/sindresorhus/awesome-lint).
26
26
27
27
No extra work is required here as it is [already integrated by the way of GitHub actions](https://github.com/kdeldycke/awesome-iam/tree/main/.github/workflows).
28
28
29
-
To run the linter locally, do:
29
+
You can still anticipate issues by running the linter locally with:
30
30
31
31
```shell-session
32
-
$ npm i npx
33
32
$ npx awesome-lint
34
33
```
35
34
36
35
## Formatting
37
36
38
-
Additional rules not covered by `awesome-lint`, to keep the content clean and tidy.
37
+
Here are additional rules not covered by the `awesome-lint` CLI.
39
38
40
39
If one of these rule conflict with the linter, the linter's rule should takes precedence. Apply it.
41
40
@@ -47,29 +46,43 @@ If one of these rule conflict with the linter, the linter's rule should takes pr
47
46
48
47
- Apostrophes should be using the single ASCII mark: `'`.
49
48
50
-
-Try to quote the original content as-is to summarize the point of the linked content.
49
+
-For description, try to identify the single best quote form the original content.
51
50
52
-
- If a straight quote doesn't cut it, feel free to paraphrase both the item's title and description. Remember, this is curation: we are increasing the value of the original content by aggregation and categorization. And also by smart editorializing. You just need to respect the spirit of the original content.
51
+
- If a quote couldn't be found to serve as a summary, feel free to paraphrase both the item's title and description. Remember, this is curation: we are increasing the value of the original content by aggregation and categorization. And also by smart editorializing. You just need to respect the spirit of the original content.
53
52
54
53
### Sections
55
54
56
-
- Sections are not in the alphabetical order, to provide a progression, from general to specific topics.
55
+
- Sections **are not intentionally sorted in the alphabetical order**. That is to provide a progression, from general to specific topics.
56
+
57
+
> [!IMPORTANT]
58
+
> Exceptionally in `awesome-falsehood`, sections **are in alphabetical order**, as all topics are independent from each others.
57
59
58
60
- Section might feature one paragraph introduction and a figure (graph, drawing, photo).
59
61
60
-
### Item title
62
+
### URL
63
+
64
+
- Use HTTPs protocol, if available.
65
+
66
+
- Must be reachable by CI/CD jobs. If the domain return `40x` errors for rate-limiting or content protection, replace it with a stable link:
61
67
62
-
- URLs must use HTTPs protocol, if available.
68
+
-[`sci-hub.st`](https://sci-hub.st) for research papers
69
+
-[`archive.ph`](https://archive.ph) for news articles
70
+
-[`archive.org`](https://archive.org) for anything else
71
+
72
+
### Item title
63
73
64
74
- No `“` and `”` curved quotation marks. This is reserved for original content quotation in descriptions.
65
75
66
76
- To quote, use either the single or double variations: `'` and `"`. Keep them properly balanced.
67
77
78
+
> [!IMPORTANT]
79
+
> In `awesome-falsehood`, link titles must be stripped out of the "*Programmers believe*" part to keep it compact.
80
+
68
81
### Item description
69
82
70
83
- Try to provide an actionable TL;DR as a description, quoting the original text if it stands by itself.
71
84
72
-
-[Removes `TL;DR:` prefix in description](https://github.com/kdeldycke/awesome-iam/commit/537cbfd8beaca18d44a0962e107a6db9171a0345). Every description is a short summary anyway.
85
+
-[Removes `TL;DR:` prefix in description](https://github.com/kdeldycke/awesome-engineering-team-management/commit/da298ec1c39fe62fd4553e1a6de0ad4494602c57). Every description is a short summary anyway.
73
86
74
87
- Quotes should be properly delimited with the `“` and `”` curved quotation marks.
75
88
@@ -79,7 +92,7 @@ If one of these rule conflict with the linter, the linter's rule should takes pr
79
92
80
93
- To serialize a list into a description, use the following format:
81
94
82
-
> Text of a description summarizing the item. And here is a list coming from the original content about **“a random subject: 1. Blah blah blah; 2. Blah blah blah? 3. Blah blah blah.”** And a bit more text to conclude.
95
+
> Text of a description summarizing the item. And here is a list coming from the original content about **“three important topics: 1. Blah blah blah; 2. Blah blah blah? 3. Blah blah blah.”** And a bit more text to conclude.
83
96
84
97
This format provides visual anchor points that help readability and quick content scanning.
85
98
@@ -89,27 +102,154 @@ If one of these rule conflict with the linter, the linter's rule should takes pr
89
102
90
103
- An additional link in the description is allowed. This must be limited to some rare cases. Like pointing to a bigger concept, an acronym definition, or reference material (book, biography, …).
91
104
92
-
### CLI helpers
105
+
## Editorial line
106
+
107
+
The general editorial line for each list is [hinted in their introduction](https://github.com/kdeldycke/awesome-template#readme).
108
+
109
+
There's also some specific rules depending on the list:
110
+
111
+
### [`awesome-engineering-team-management`](https://github.com/kdeldycke/awesome-engineering-team-management): items order
112
+
113
+
Items are roughly ordered like so:
114
+
115
+
1. At first we'll find content appealing to software developers or new managers. We're reaching for accessibility and targets the wider audience and provide a gentle introduction.
116
+
1. Then we can have a couple of real use-cases or anecdotes, which makes the subject more hands-on and relatable.
117
+
1. Third we might add a couple of reference material to generalize concepts, provide methodical solutions and expose broader thinking frameworks.
118
+
1. At the end comes the most cynical or bleak content, which have some utility as cautionary tales, or as warning signals of deteriorating conditions.
Before contributing, make sure the new link you'd like to add is a good
123
+
candidate.
124
+
125
+
Here is a non-restrictive list of items which are good candidates for inclusion
126
+
in the `awesome-falsehood` list.
127
+
128
+
#### Falsehood articles
129
+
130
+
Articles following the *falsehood* schema are prime candidates for inclusion in
131
+
this awesome list.
132
+
133
+
These articles starts with the hypothesis that developers have a naive and
134
+
simple view of a domain. Then proceed to list a set of candid assumptions that
135
+
might be held by programmers. Each one is intentionally false, and in their
136
+
best form are illustrated with a counter-example.
137
+
138
+
A list of falsehood is crafted as a progression that is designed to refine
139
+
concepts. Having read the whole list of falsehood, the reader should possess a
140
+
better overview of a domain while dispelling its myths, point out common
141
+
pitfalls and demonstrate its subtleties.
142
+
143
+
*falsehood* articles are, in a sense, a suite of wordy unit-tests covering
144
+
extensive edge-cases provided by real-world usage. The world is messy.
145
+
Discovering a domain to be much more complex than anticipated will lead to
146
+
frustrations. And cause flipping tables `(╯°□°)╯︵ ┻━┻`. This is the sign of a
147
+
great candidate for that list!
148
+
149
+
Articles featuring items that are applicable to one product (or a service) and
150
+
one only can't be considered as generic enough and should be avoided.
151
+
152
+
#### Libraries
153
+
154
+
Programming libraries or modules are good candidates too, if they solve or
155
+
reduce the complexities pointed to by *falsehood* articles above.
156
+
157
+
That way we can put back tables in place. `┬─┬ ノ( ゜-゜ノ)`
158
+
159
+
#### Data structures
160
+
161
+
Data models and structures generic enough to cover and address most of the
162
+
falsehoods are also welcome in this page.
163
+
164
+
## FAQ
165
+
166
+
Some cases to illustrate the curation process.
167
+
168
+
### Can I rewrite your sentences and paragraphs?
169
+
170
+
Yes. I'm a non-native speaker, so some of my writings might be a little bit fancy. If you can propose a shorter, to the point, and accurate version of my initial text, go for it! These improvements [adds a lot of readability for both kind of readers](https://github.com/kdeldycke/awesome-falsehood/pull/105).
171
+
172
+
### Can I propose YouTube videos for the list?
173
+
174
+
Yes, but try to pin-point the start of the video to a relevant time. Like with the `&t=13m30s` parameter in YouTube URLs.
175
+
176
+
Better than a video: have a link to its written transcript. Or presentation slides if it doesn't dillute the point being made.
177
+
178
+
### Can I link to an X thread?
179
+
180
+
Yes, but try to search first in the content produced by the author: sometimes the said author edited its rant into a more digestible article elsewhere. We'll prefer to link to that.
181
+
182
+
### How to prevent link-rot?
183
+
184
+
[As pointed by a contributor](https://github.com/kdeldycke/awesome-engineering-team-management/issues/52#issue-1499417056):
185
+
186
+
> The links here have a tendency to go offline. For this to be a resource of long term value, link-rot can be avoided by archiving the pages.
187
+
188
+
Which is true.
189
+
190
+
I have no issue replacing the original URL with an alternative archived/cached link if the original is no longer reachable.
191
+
192
+
Broken URLs are frustrating. We will fix them one by one. Some have been moved to a new domain. Some have completely disappear, so we'll replace them with a `archive.org` link.
193
+
194
+
If you find a broken one, please propose a PR to fix it. Or just report it as an issue and I'll do the work.
195
+
196
+
### How are you going to archive articles that went offline?
197
+
198
+
This question points to the paradox that we need to archive them *before* they go offline.
199
+
200
+
There is no rush to pre-emptively archive content. Incentives exists for others to do it:
201
+
202
+
- This list is popular enough for its content to be picked up by regular archival crawlers.
203
+
- Popular content in this list are naturally archived by users who value them.
204
+
- Authors who cares about their content, or benefits from the SEO juice this list provides, have an incentive to keep them available at their original URL.
205
+
206
+
Despites these incentives, there is still a non-zero chance for content to disappear entirely from the web, with no archived copy in `archive.org`. That's not the end of the world. Maybe the content wasn't worth it, and not good for inclusion in the first place. Think of this edge-case as a natural selection process on content, which helps natural curation.
207
+
208
+
### Why removes inactive GitHub projects?
209
+
210
+
Unmaintained GitHub repositories are usually [archived by their owners](https://docs.github.com/en/repositories/archiving-a-github-repository/archiving-repositories). But some are de-facto unmaintained, or abandoned as-is by their author, without being explicitly archived.
211
+
212
+
Either way, if the space they addresses is crowded, and there are other repositories referenced in the list, the link is a good candidate for deletion to reduce noise.
213
+
214
+
On the other hand, if the project has been forked or rebooted elsewhere, we can now point out to the new location.
215
+
216
+
### Why my commercial project is not in the list?
217
+
218
+
Probably because the core content is behind a paywall. Especially if there are better resources online, which are more extensive, and freely accessible.
219
+
220
+
This is especially true for SaaS and other licensed software. If there is an open-source project available, we'd rather point to that instead of commercial solutions.
221
+
222
+
These alternatives don't need to be better. They qualify if they're good enough to derives inspiration from, or starts something without barriers to entry.
223
+
224
+
So for as set of multiple overlapping projects, we will consider commercial ones as duplicates and remove them, to keep the list lean.
225
+
226
+
### Why my link was rejected?
227
+
228
+
If your link was rejected, it must have been motivated and explained to the contributor as a comment to your PR.
229
+
230
+
Some reasons for rejection, which often overlaps, includes:
231
+
232
+
- deviance from these contribution guidelines
233
+
- violation of the [code of conduct](code-of-conduct.md)
234
+
- duplicate content
235
+
- lack of motivation in what the new link adds to the existing corpus
236
+
- lack of originality
237
+
- overcrowded section that [needs more curation than additional content](https://github.com/kdeldycke/awesome-iam/pull/76)
238
+
-[commercially-sponsored content only proposed for SEO](https://github.com/kdeldycke/awesome-falsehood/pull/31#issuecomment-407667679)
239
+
- lack of feedback from the contributor on raised questions
93
240
94
-
One-liners to fix-up some common formatting mistakes. Use with great caution and always double-check and edit the results.
241
+
### How can I force a link into the list?
95
242
96
-
- Replaces star list item markers by dashes:
243
+
If your contribution has been declined, there is a way to bypass the curation rules. You can [purchase a sponsorship](https://github.com/sponsors/kdeldycke) and have your product, logo and link at the top of this repository! 🤗 Like [Descope did for a year](https://twitter.com/kdeldycke/status/1676963147104784386) on the [awesome IAM list](https://twitter.com/kdeldycke/status/1676963147104784386).
97
244
98
-
```shell-session
99
-
$ sed -i 's/^* /- /g' ./README.md
100
-
```
245
+
## FAQ for [`awesome-falsehood`](https://github.com/kdeldycke/awesome-falsehood)
101
246
102
-
- Replaces typographic quotes with ASCII ones:
247
+
This questions are specifics to the [Awesome Falsehood](https://github.com/kdeldycke/awesome-falsehood) project.
103
248
104
-
```shell-session
105
-
$ sed -i "s/‘/\'/g" ./readme.md
106
-
$ sed -i "s/’/\'/g" ./readme.md
107
-
```
249
+
### Why don't you copy the falsehoods in the list?
108
250
109
-
- Forces quotes to end with a dot:
251
+
This might be a good idea to compile all falsehoods in the repository. It would allow the community to maintain them, and enrich them. It could also improve the overall quality as most external articles don't make the effort to illustrate or explain why a falsehood is a falsehood.
110
252
111
-
```shell-session
112
-
$ sed -i 's/`$/`\./g' ./readme.md
113
-
```
253
+
But that is a big endeavor, so to keep things simple, we just make a collection of external articles in this list. In the mean time, if you'd like to add falsehoods, I will ask potential contributors to [host them elsewhere](https://github.com/kdeldycke/awesome-falsehood/issues/46).
114
254
115
-
[Other one-liners are available](https://kevin.deldycke.com/2006/text-date-document-processing-commands/) on my blog.
255
+
Also, if we had to host the raw falsehoods in this repository, we might have to [check on the licence and seek permission from the original author](https://github.com/kdeldycke/awesome-falsehood/issues/24#issuecomment-354112401).
0 commit comments