While the basics are relatively simple, there is a great diversity in the resources we list. Here are some notes on how we deal with this diversity.
雖然基本原則相對簡單，但我們列出的資源種類繁多。以下是我們如何處理這些多樣性的說明。
#### Metadata
#### 元數據（Metadata）
Our lists provide a minimal set of metadata: titles, URLs, creators, platforms, and access notes.
我們的列表僅提供最基本的元數據：標題、網址、創作者、平台以及存取說明。
##### Titles
##### 標題
- No invented titles. We try to take titles from the resources themselves; contributors are admonished not to invent titles or use them editorially if this can be avoided. An exception is for older works; if they are primarily of historical interest, a year in parentheses appended to the title helps users know if they are of interest.
- No ALLCAPS titles. Usually title case is appropriate, but when doubt use the capitalization from the source
- We want to credit the creators of free resources where appropriate, including translators!
- For translated works the original author should be credited. We recommend using [MARC relators](https://loc.gov/marc/relators/relaterm.html) to credit creators other than authors, as in this example:
* [A Translated Book](http://example.com/book-zh.html) - John Doe, `trl.:` Mike The Translator
* [中文翻譯版](http://example.com/book-zh.html) - John Doe, `trl.:` Mike The Translator
```
here, the annotation `trl.:` uses the MARC relator code for "translator".
- Use a comma `,` to delimit each item in the author list.
- 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`".
- 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.
- 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)*`.
The first rule in deciding which list a resource belongs in is to see how the resource describes itself. If it calls itself a book, then maybe it's a book.
決定資源歸屬於哪個列表的首要規則是看資源如何自我描述。如果它稱自己是一本書，那麼它就是一本書。
##### Genres we don't list
##### 我們不列出的資源類型
Because the Internet is vast, we don't include in our lists:
由於網際網路內容浩瀚無邊，我們的列表不包含以下內容：
- blogs
- blog posts
- articles
- websites (except for those that host LOTS of items that we list).
- videos that aren't courses or screencasts.
- book chapters
- teaser samples from books
- IRC or Telegram channels
- Slacks or mailing lists
- 部落格
- 部落格文章
- 文章
- 網站（除非該網站包含我們列出的大量資源）
- 不是課程或螢幕錄製的影片
- 書籍章節
- 書籍的試閱樣章
- IRC 或 Telegram 頻道
- Slack 或郵件列表
Our competitive programming lists are not as strict about these exclusions. The scope of the repo is determined by the community; if you want to suggest a change or addition to the scope, please use an issue to make the suggestion.
We're not that fussy about book-ness. Here are some attributes that signify that a resource is a book:
我們對書籍的定義並不那麼嚴格，但以下特徵通常表明該資源是書籍：
- it has an ISBN (International Standard Book Number)
- it has a Table of Contents
- a downloadable version is offered, especially ePub files.
- it has editions
- it doesn't depend on interactive content or videos
- it tries to comprehensively cover a topic
- it's self-contained
- 它有 ISBN（國際標準書號）
- 它有目錄
- 提供可下載的版本，特別是 ePub 文件
- 它有不同版本
- 它不依賴互動內容或影片
- 它試圖全面涵蓋某一主題
- 它是自成一格的
There are lots of books that we list that don't have these attributes; it can depend on context.
我們列出的許多書籍不一定具備這些特徵，具體情形取決於上下文。
##### Books vs. Courses
##### 書籍與課程的區別
Sometimes these can be hard to distinguish!
有時這兩者很難區分！
Courses often have associated textbooks, which we would list in our books lists. Courses have lectures, exercises, tests, notes or other didactic aids. A single lecture or video by itself is not a course. A powerpoint is not a course.
Y.K. Lin
1 month ago
committed by
GitHub