add guidance for things that have confused submitters (#8152)

* add guidance that has been and issue

* add notes on time limits
pull/8197/head
Eric Hellman 2 years ago committed by GitHub
parent 9461369283
commit 933bb43f73
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
  1. 13
      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)*`.

Loading…
Cancel
Save