From 933bb43f73b0c7e58688e39dddb1608a1ca9691a Mon Sep 17 00:00:00 2001 From: Eric Hellman Date: Wed, 12 Oct 2022 22:11:42 -0400 Subject: [PATCH] add guidance for things that have confused submitters (#8152) * add guidance that has been and issue * add notes on time limits --- docs/CONTRIBUTING.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 2afbfc76f..6700030fb 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -114,7 +114,7 @@ Example: GOOD: * [A Very Awesome Book](https://example.org/book.pdf) - Jane Roe (PDF) ``` -- Multiple formats: +- Multiple formats (We prefer a single link for each resource. When there is no single link with easy access to different formats, multiple links may make sense. But every link we add creates maintenance burden so we try to avoid it.): ```text BAD : * [Another Awesome Book](http://example.com/)- John Doe (HTML) @@ -189,13 +189,22 @@ Our lists provide a minimal set of metadata: titles, URLs, creators, platforms, - You can shorten author lists with "`et al.`". - We do not permit links for Creators. - For compilation or remixed works, the "creator" may need a description. For example, "GoalKicker" or "RIP Tutorial" books are credited as "`Compiled from StackOverflow documentation`". +- We do not include honorifics such as "Prof." or "Dr." in creator names. + + +##### Time-limited Courses and Trials + +- We don't list things that we'll need to remove in six months. +- If a course has a limited enrollment period or duration, we won't list it. +- We can't list resources that are free for a limited period. ##### Platforms and Access Notes - Courses. Especially for our course lists, the platform is an important part of the resource description. This is because course platforms have different affordances and access models. While we usually won't list a book that requires a registration, many course platforms have affordances that don't work without some sort of account. Example course platforms include Coursera, EdX, Udacity, and Udemy. When a course depends on a platform, the platform name should be listed in parentheses. - YouTube. We have many courses which consist of YouTube playlists. We do not list YouTube as a platform, we try to list the YouTube creator, which is often a sub-platform. -- YouTube videos. We usually don't link to individual YouTube videos unless they are more than an hour long and are structured like a course or a tutorial. +- YouTube videos. We usually don't link to individual YouTube videos unless they are more than an hour long and are structured like a course or a tutorial. If this is the case, be sure to make a note of it in the PR description. +- No shortened (i.e. youtu.be/xxxx) links! - Leanpub. Leanpub hosts books with a variety of access models. Sometimes a book can be read without registration; sometimes a book requires a Leanpub account for free access. Given quality of the books and the mixture and fluidity of Leanpub access models, we permit listing of the latter with the access note `*(Leanpub account or valid email requested)*`.