docs(CONTRIBUTING): complete creators guidelines with relator terms (#…

…7102) * complete creators guidelines with relator terms * Update CONTRIBUTING.md minor language editing * Update CONTRIBUTING.md recover missing MARC relators URL to complete empty link * chore: copy ENG missing texts to translated files * chore: translate new texts to spanish * chore: translate new text to italian Co-authored-by: ImVector <[email protected]> Co-authored-by: Eric Hellman <[email protected]> Co-authored-by: ImVector <[email protected]>
EbookFoundation · Sep 29, 2022 · e091eee · e091eee
1 parent d3caf74
commit e091eee
Show file tree

Hide file tree

Showing 15 changed files with 503 additions and 28 deletions.
diff --git a/docs/CONTRIBUTING-de.md b/docs/CONTRIBUTING-de.md
@@ -56,6 +56,7 @@ Durch Deine Mitwirkung verpflichtest Du Dich, dem [Verhaltenskodex](CODE_OF_COND
 - Vermerke das Datum der Veröffentlichung im Titel, wenn es sich um ein älteres Buch handelt.
 - Erfasse gegebenenfalls den Namen des oder der Autoren. Eine längere Liste von Autoren kann mit dem Zusatz "`et al.`" gekürzt werden.
 - Wenn das Buch noch nicht fertiggestellt ist und sich noch in Bearbeitung befindet, füge wie [unten](#in_process) beschrieben einen "`in process`" Hinweis hinzu.
+- if a resource is restored using the [*Internet Archive's Wayback Machine*](https://web.archive.org) (or similar), add the "`archived`" notation, as described [below](#archived). The best versions to use are recent and complete.
 - Wenn eine funktionierende E-Mail Adresse oder das Einrichten eines Benutzerkontos vor Aktivierung des Downloads erbeten wird, sollten angemessene Hinweise in Klammern angegeben werden, z.&nbsp;B.: `(E-Mail Adresse *erbeten*, nicht erforderlich)`.
 
 
@@ -134,6 +135,12 @@ Beispiel:
     RICHTIG: * [Wird bald ein tolles Buch sein](http://example.com/book2.html) - John Doe (HTML) (:construction: *in Bearbeitung*)
     ```
 
+- <a id="archived"></a>Archived link:
+
+    ```text
+    RICHTIG: * [A Way-backed Interesting Book](https://web.archive.org/web/20211016123456/http://example.com/) - John Doe (HTML) *(:card_file_box: archived)*
+    ```
+
 ### Alphabetische Sortierung
 
 - Wenn mehrere Titel mit demselben Buchstaben beginnen, sortiere sie nach dem zweiten Buchstaben und so weiter. Zum Beispiel folgt `ab` nach `aa`.
@@ -171,9 +178,17 @@ Unsere Listen enthalten einen minimalen Satz an Metadaten: Titel, URLs, Autoren,
 ##### Urheber
 
 - Wir wollen alle Urheber kostenloser Inhalte angemessen nennen, inklusive eventueller Übersetzer!
-- For übersetzte Werke sollte der Autor des ursprünglichen Werks genannt werden.
+- For übersetzte Werke sollte der Autor des ursprünglichen Werks genannt werden. We recommend using [MARC relators](https://loc.gov/marc/relators/relaterm.html) to credit creators other than authors, as in this example:
+
+    ```markdown
+    * [A Translated Book](http://example.com/book-de.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.`".
 - Wir erlauben keine Links für Urheber.
-- Für Sammlungen oder neu zusammengestellte Werke, benötigt der "Urheber" eventuell eine Beschreibung. Bücher von "GoalKicker" werden z.&nbsp;B. als "`Zusammengestellt aus StackOverflow Dokumentationen`" (auf englisch: "`Compiled from StackOverflow documentation`") gekennzeichnet.
+- Für Sammlungen oder neu zusammengestellte Werke, benötigt der "Urheber" eventuell eine Beschreibung. Bücher von "GoalKicker" oder "RIP Tutorial" werden z.&nbsp;B. als "`Zusammengestellt aus StackOverflow Dokumentationen`" (auf englisch: "`Compiled from StackOverflow documentation`") gekennzeichnet.
 
 
 ##### Plattformen und Zugriffshinweise

diff --git a/docs/CONTRIBUTING-el.md b/docs/CONTRIBUTING-el.md
@@ -172,7 +172,7 @@ If you see a misplaced link, check the linter error message to know which lines
 - No emojis.
 
 
-#### URLs
+##### URLs
 
 - Δεν επιτρέπουμε περικομμένα URLs.
 - Κωδικοί ανίχνευσης πρέπει να αφαιρεθούν από το URL.
@@ -181,15 +181,23 @@ If you see a misplaced link, check the linter error message to know which lines
 - Δεν μας αρέσουν URLs που οδηγούν σε ιστοσελίδες που δεν φιλοξενούν το υλικό που αναφέρεται, αλλά αντ' αυτού οδηγούν αλλού.
 
 
-#### Δημιουργοί
+##### Δημιουργοί
 
 - Θέλουμε να αναφέρονται τα ονόματα των δημιουργών δωρεάν υλικού όπου κρίνεται κατάλληλο, συμπεριλαμβανομένων των μεταφραστών!
-- Για μεταφρασμένα έργα, θα πρέπει να αναφέρεται το όνομα του αρχικού συγγραφέα.
+- Για μεταφρασμένα έργα, θα πρέπει να αναφέρεται το όνομα του αρχικού συγγραφέα. We recommend using [MARC relators](https://loc.gov/marc/relators/relaterm.html) to credit creators other than authors, as in this example:
+
+    ```markdown
+    * [A Translated Book](http://example.com/book-el.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.`".
 - Δεν επιτρέπουμε συνδέσμους για Δημιουργούς.
 - Για συλλεγμένα ή επεξεργασμένα έργα, ο "δημιουργός" ίσως χρειάζεται περιγραφή. Για παράδειγμα, τα βιβλία από το "GoalKicker" ή "RIP Tutorial" αναφέρονται ως "`Συντάχθηκαν από documentation του StackOverflow`" (στα αγγλικά: "`Compiled from StackOverflow documentation`").
 
 
-#### Πλατφόρμες και Σημειώσεις Πρόσβασης
+##### Πλατφόρμες και Σημειώσεις Πρόσβασης
 
 - Μαθήματα. Ειδικά για τις λίστες μαθημάτων μας, η πλατφόρμα είναι ένα σημαντικό κομμάτι της περιγραφής του υλικού. Αυτό επειδή οι πλατφόρμες με μαθήματα έχουν διαφορετική προσβασιμότητα και μοντέλα πρόσβασης. Ενώ συνήθως δεν θα προσθέσουμε ένα βιβλίο που απαιτεί εγγραφή, πολλές πλατφόρμες μαθημάτων έχουν χαρακτηριστικά που δεν θα δουλέψουν χωρίς κάποιο τύπο λογαριασμού. Παραδείγματα πλατφορμών μαθημάτων περιλαμβάνουν τα Coursera, EdX, Udacity και Udemy. Όταν ένα μάθημα εξαρτάται από την πλατφόρμα, το όνομα της πλατφόρμας θα πρέπει να αναφέρεται σε παρένθεση.
 - YouTube. Έχουμε πολλά μαθήματα που αποτελούνται από playlists στο YouTube. Δεν παραθέτουμε το YouTube σαν πλατφόρμα, προσπαθούμε να αναφέρουμε τον δημιουργό στο YouTube, που είναι συνήθως υπό-πλατφόρμα.
@@ -203,7 +211,7 @@ If you see a misplaced link, check the linter error message to know which lines
 Ο πρώτος κανόνας στην απόφαση για το σε ποια λίστα ανήκει το υλικό είναι να δείτε πώς περιγράφει τον εαυτό του. Αν αυτοαποκαλείται βιβλίο, τότε ίσως είναι βιβλίο.
 
 
-#### Είδη που δεν παραθέτουμε
+##### Είδη που δεν παραθέτουμε
 
 Επειδή το Internet είναι μεγάλο, δεν περιέχουμε στις λίστες μας:
 
@@ -220,7 +228,7 @@ If you see a misplaced link, check the linter error message to know which lines
 Οι λίστες μας ανταγωνιστικού προγραμματισμού δεν είναι το ίδιο αυστηρές με αυτούς τους αποκλεισμούς. Τα περιθώρια αυτού του αποθετηρίου αποφασίζονται από την κοινότητα· αν θέλετε να προτείνετε μια αλλαγή ή μια προσθήκη στον σκοπό, παρακαλούμε χρησιμοποιήστε ένα issue για να κάνετε μια πρόταση.
 
 
-#### Βιβλία vs. Άλλα Πράγματα
+##### Βιβλία vs. Άλλα Πράγματα
 
 Δεν είμαστε τόσο γκρινιάρηδες για την βιβλιό-τητα. Ορίστε μερικά χαρακτηριστικά που εκφράζουν ότι το υλικό είναι βιβλίο:
 
@@ -235,7 +243,7 @@ If you see a misplaced link, check the linter error message to know which lines
 Υπάρχουν πολλά βιβλία που παραθέτουμε που δεν έχουν αυτά τα χαρακτηριστικά· μπορεί να εξαρτάται από την περίπτωση.
 
 
-#### Βιβλία vs. Μαθήματα
+##### Βιβλία vs. Μαθήματα
 
 Μερικές φορές μπορεί να είναι δύσκολο να τα ξεχωρίσουμε!
 

diff --git a/docs/CONTRIBUTING-es.md b/docs/CONTRIBUTING-es.md
@@ -190,7 +190,15 @@ Nuestros listados proporcionan un conjunto mínimo de metadatos: títulos, URL,
 ##### Atribuciones
 
 - Queremos dar crédito a los creadores de recursos gratuitos cuando sea apropiado, ¡incluso traductores!
-- En el caso de obras traducidas, se debe acreditar también al autor original.
+- En el caso de obras traducidas, se debe acreditar también al autor original. Recomendamos usar [MARC relators](https://loc.gov/marc/relators/relaterm.html) para dar presencia al resto de creadores diferentes al autor original, tal y como se muestra en este ejemplo:
+
+    ```markdown
+    * [Un libro traducido](http://example.com/book-es.html) - John Doe, `trl.:` Mike Traduce
+    ```
+
+    donde, la anotación `trl.:` incluye el código MARC relator para "traductor".
+- Utilice comas `,` para separar cada elemento de la lista de autores.
+- Cuando sean muchas, puedes valerte de "`et al.`" para acortar dicha lista.
 - No permitimos enlaces directos al creador.
 - En el caso de recopilaciones u obras remezcladas, el "creador" puede necesitar una descripción. Por ejemplo, los libros de "GoalKicker" o "RIP Tutorial" se acreditan como "`Creado a partir de la documentación de StackOverflow`" (en inglés: "`Compiled from StackOverflow documentation`").
 

diff --git a/docs/CONTRIBUTING-fa_IR.md b/docs/CONTRIBUTING-fa_IR.md
@@ -59,6 +59,7 @@
 * اگر کتاب قدیمی است، تاریخ انتشار را در کنار عنوان بنویسید.
 * نام نویسنده یا نویسندگان را در صورت امکان بنویسید. می‌توانید فهرست نویسندگان را با "و همکاران" (به انگلیسی: "`et al.`") کوتاه کنید.
 * اگر کتاب هنوز تمام نشده است و هنوز روی آن کار می‌شود، عبارت "`in process`" را همان طور که در [پایین صفحه](#in_process) آمده به آن اضافه کنید.
+- if a resource is restored using the [*Internet Archive's Wayback Machine*](https://web.archive.org) (or similar), add the "`archived`" notation, as described [below](#archived). The best versions to use are recent and complete.
 * اگر پیش از دانلود، نشانی ایمیل یا ساخت حساب کاربری خواسته می‌شود، در پرانتز توضیح متناسبی بنویسید. مثلا: `(نشانی ایمیل *خواسته می‌شود* اما اجباری نیست)`.
 
 
@@ -138,6 +139,11 @@
     خوب: * [کتابی که عالی خواهدشد](http://example.com/book2.html) - نام نویسنده (HTML) (:construction: *in process*)
     ```
 
+- <a id="archived"></a>Archived link:
+
+    ```text
+    خوب: * [A Way-backed Interesting Book](https://web.archive.org/web/20211016123456/http://example.com/) - John Doe (HTML) *(:card_file_box: archived)*
+    ```
 
 ### ترتیب الفبایی
 
@@ -147,6 +153,105 @@
 اگر لینکی را در جای نادرست دیدید، پیام خطای linter را ببینید تا بفهمید کدام خط‌ها باید جابجا شوند.
 
 
+### 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 capitalization from the source
+- No emojis.
+
+
+##### 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 recommend using [MARC relators](https://loc.gov/marc/relators/relaterm.html) to credit creators other than authors, as in this example:
+
+    ```markdown
+    * [A Translated Book](http://example.com/book-fa_IR.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`".
+
+
+##### 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 (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
+
+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.
+
+
 ### خودکارسازی
 
 * قوانین فرمت‌بندی از طریق [GitHub Actions](https://docs.github.com/en/actions) با استفاده از [fpb-lint](https://github.com/vhf/free-programming-books-lint) بررسی می‌شوند ([`.github/workflows/fpb-lint.yml`](../.github/workflows/fpb-lint.yml) را ببینید)

diff --git a/docs/CONTRIBUTING-fil.md b/docs/CONTRIBUTING-fil.md
@@ -180,7 +180,15 @@ Nagbibigay ang aming mga listahan ng kaunting hanay ng metadata: mga pamagat, UR
 ##### Mga tagalikha
 
 - Gusto naming pasalamatan ang mga lumikha ng mga libreng mapagkukunan kung saan naaangkop, kabilang ang mga tagasalin!
-- Para sa mga isinaling gawa ang orihinal na may-akda ay dapat na kredito.
+- Para sa mga isinaling gawa ang orihinal na may-akda ay dapat na kredito. We recommend using [MARC relators](https://loc.gov/marc/relators/relaterm.html) to credit creators other than authors, as in this example:
+
+    ```markdown
+    * [A Translated Book](http://example.com/book-fil.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.`".
 - Hindi namin pinahihintulutan ang mga link para sa Mga Tagalikha.
 - Para sa compilation o remixed na mga gawa, maaaring kailanganin ng "creator" ang isang paglalarawan. Halimbawa, ang mga aklat na "GoalKicker" o "RIP Tutorial" ay kinikilala bilang "`Compiled from StackOverflow Documentation`".