@@ -119,7 +119,91 @@ GOOD: * [A Very Awesome Book (1970)](https://example.org/book.html) - Jane Roe
GOOD: * [Will Be Awesome Soon Book](http://example.com/book2.html) - John Doe (HTML) (:construction: *in process*)
```
### Notes
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
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 captitalization from the source
##### URLs
- We don't permit shortened URLs.
- Tracking codes must be removed from the URL.
- International URLs should be escaped. Browser bars typically render these to Unicode, but use copy and paste, please.
- Secure (https) URLs are always preferred over non-secure (http) urls where https has been implemented.
- 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 do not permit links for Creators.
- For compilation or remixed works, the "creator" may need a description. For example, "GoalKicker" books are credited as "Compiled from StackOverflow documentation"
##### 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.
- 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)*
#### Genres
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
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.
##### Books vs. Other Stuff
We're not that fussy about book-ness. Here are some attributes that signify that a resource is a book:
- it has an ISBN
- it has a Table of Contents
- a downloaded version, especially ePub, is offered
- 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.
##### Interactive Tutorials vs. Other stuff
If you can print it out and retain its essence, it's not an Interactive Tutorial.
### Automation
- Formatting rules enforcement is automated via [Travis CI](https://travis-ci.com) using [fpb-lint](https://github.com/vhf/free-programming-books-lint)(see[.travis.yml](.travis.yml))
