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.
- Secure (`https`) URLs are always preferred over non-secure (`http`) urls where HTTPS has been implemented.
- 若情況允許，應優先使用安全的網址（https），避免使用不安全的網址（http）。
- We don't like URLs that point to webpages that don't host the listed resource, but instead point elsewhere.
- 我們不喜歡指向與所列資源無關的網頁，也不接受這類轉址鏈接。
##### Creators
##### 創作者
- 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".
在這裡，註記 trl.: 使用了 MARC 關係代碼來標示 “翻譯者”。
- Use a comma `,` to delimit each item in the author list.
- 作者列表中的每個項目以逗號 `,` 分隔。
- You can shorten author lists with "`et al.`".
- 可以使用 “`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
- IRC 或 Telegram 頻道
- Slacks or mailing lists
- 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)
- 它有 ISBN（國際標準書號）
- it has a Table of Contents
- 它有目錄
- a downloadable version is offered, especially ePub files.
- 提供可下載的版本，特別是 ePub 文件
- it has editions
- 它有不同版本
- it doesn't depend on interactive content or videos
- 它不依賴互動內容或影片
- it tries to comprehensively cover a topic
- 它試圖全面涵蓋某一主題
- it's self-contained
- 它是自成一格的
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