Annotate Librarian Guide

This guide covers how to use the librarian tools to manage the Annotate database, handle reader tickets, and add new books.

1. Getting Started

1.1 Getting Access

Both librarian tools use your standard Annotate login. However, the developer must enable the librarian permissions on your account first. If you see a permission error when trying to log in, message a Lead Librarian.

Note: The tools have separate sessions, so you will need to log into each one individually.

Every edit you make is logged. This isn't to police you; it just allows us to revert mistakes if something goes wrong. Don't be afraid to make changes.

1.2 The Tools

You will primarily use two interfaces for this job:

Usually, you will read a request in the Tickets tool and fulfill it in the Portal.

1.3 The Ticket Board

The ticket board tracks reader submissions. You can open a ticket to copy its data, "Pick up" a ticket to assign it to yourself, or drag it between columns.

Ticket Type What it means
report_info Correction to a book's fields.
add_book New book submission.
add_series Adding a book to a series.
add_edition New edition submission.

Some tickets are "flag only" (meaning the reader reported an error but didn't provide the fix) or scoped to a specific edition.

2. Database Structure

2.1 Books vs. Editions

Understanding the difference between a book and an edition is the most important part of this job.

Book Record (General) Edition Records (Specific)
Dune by Frank Herbert Ace, 1990 (ISBN 0441172717) - 412 pages
Gollancz, 2015 (ISBN 9781473224469) - 608 pages

Rule of thumb: If you are fixing details that apply to the story universally, edit the Book. If you are fixing a specific cover, ISBN, or page count, edit the Edition.

Translations are editions, not new books. A book and its translations are the same work. Orgueil et Préjugés is not a separate book, it is the French edition of Pride and Prejudice. It belongs under the existing book with its Language set to French, never as a new Book row.

How to title the Book: if a work has an English translation, the Book title is the English title (Pride and Prejudice), and every other language lives underneath it as an edition. A work that has no English translation yet is titled in its original language and added as its own Book. That second case is the kind of non-English book Section 10 asks you to help catalog.

What is the ISBN on Book: If a book is just the work, then why is an ISBN mandatory when adding a book? This is the default edition for a book. Pick the most popular edition when entering a book and enter that ISBN here.

Study guides and textbooks: For textbooks on classics, such as SparkNotes editions, please consider them as separate entries from the classic itself. Do not add them as an edition to the classic work, as the content of these guides varies greatly from the original text.

2.2 Adding a Book

Always search the portal first to make sure the work isn't already there. Search by the English title (or the original title, for a work that has no English translation) and the author, not by the copy in your hand. A French or Spanish version will not show up under its translated title, and it will not be caught as a duplicate if you add it, so this search is the only thing standing between us and two records for the same story.

If the work already exists, you are not adding a book. Add your version as an edition instead. Only click Add Book when the work genuinely isn't in the database yet.

When you do add one, you must include a Title, Author, Cover, and Synopsis. Regular books require an ISBN, while audiobooks require a run-time. Again, rely heavily on the autocomplete for authors and languages.

2.2.1 Which ISBN goes on a new book?

The book record doubles as its default edition, the version a reader sees before they pick a specific one. So the ISBN you enter should be the main, most widely available edition of the work (for an English-titled book, the common English paperback), not the barcode of whatever specific or foreign-language copy you happen to be holding.

Do not scan the barcode of a French paperback and add it as a new book. That creates a duplicate work. The French copy is an edition of the existing English-titled book, added with its Language set to French.

2.3 Managing Editions

Click the Editions button on a book's row to manage its specific versions. There are two types:

If an Open Library edition has incorrect data (like a missing cover), click Add corrected version next to it. This copies the data into a new Custom Edition so you can fix the error without retyping everything.

Adding a translation: a different-language version of a book is a Custom Edition on the existing book. Create it there and set its Language (e.g. French), along with that edition's own title, cover, ISBN, and page count. Do not create a second book for it.

Covers are optional on editions. Leave the Cover URL blank and the edition just shows the book's cover in the app, exactly like a blank Synopsis falls back to the book's synopsis. Only fill it in when the edition genuinely has a different cover.

2.4 Editing a Book

To edit general book metadata, search for the title, author, or ISBN in the portal and click Edit. You can change:

Important: Always use the autocomplete dropdown for Authors, Series, and Languages. Typing them manually often creates duplicates.

2.5 Merging Duplicates

Use the Merge Names and Merge Books buttons in the toolbar to clean up duplicates. Merges are permanent, so proceed carefully.

Always use the "Preview merge" feature first. It will show you exactly what data will be moved and whether any reviews will be deleted. Reviews are only deleted if a user has reviewed both books being merged. In that case, the text review on the losing book is removed, as duplicate reviews cannot exist for the same book.

3. Research & Decision Making

3.1 Where to Find Correct Information

When you need to verify a reader's report or fill in missing details, here is the best order of operations:

3.2 Choosing the Main Edition

Many books have multiple editions. The goal is to choose the edition that the majority of users are most likely to own or look for, making it as easy as possible for them to find the correct book.

When deciding which edition should be the main edition, consider the following:

Remember: The purpose of the main edition is to represent the version that will be most useful for the largest number of users, not necessarily the first edition ever published.

3.3 Publisher Information

When adding or correcting publisher information, keep publisher names consistent.

Some publishing houses have multiple imprints or subdivisions and publisher names may appear with different spellings across platforms. To avoid inconsistencies:

4. Metadata Guidelines

4.1 General Guidelines

4.1.1 Language Formatting

Always enter the language name in lowercase.

Correct examples:

Do not use abbreviations (e.g. eng, fr, jpn), incorrect capitalisation or multiple languages.

4.1.2 Philippine Languages

Books written in Filipino/Tagalog should always be tagged as filipino, not tagalog.

For other Philippine languages, use the language names defined by the ISO 639 standard. The Wikipedia list of Philippine languages can also be used as a supplementary reference when needed.

Some of the most common language names are:

Use Instead of
cebuano bisaya, binisaya, bisayan, visayan
iloko ilocano, ilokano, iloco
hiligaynon ilonggo, binisaya, inilonggo
bikol bicolano, bikolano
kapampangan pampango, pampanga, pampangan
pangasinan pangasinense

4.1.3 Portuguese vs Brazilian Portuguese

Although Portuguese and Brazilian Portuguese are varieties of the same language, they should be treated as separate languages in the database.

Brazilian Portuguese and European Portuguese differ in spelling, vocabulary, idiomatic expressions, verb conjugation, punctuation conventions, and, in some cases, the meanings of words. Because of these differences, publishers often release separate editions for the Brazilian and European Portuguese markets, with different translations, titles, spelling conventions, release dates and other localised adaptations.

Examples:

A Menina que Roubava Livros (Brazil) / A Rapariga que Roubava Livros (Portugal)

O Apanhador no Campo de Centeio (Brazil) / À Espera no Centeio (Portugal)

When adding or editing a book, always tag the language according to the edition:

Keeping these categories separate makes it easier for users to find the exact edition they are looking for and helps maintain a consistent, organised database.

Note: While other Portuguese-speaking countries may have their own regional variations, creating separate categories for every country would be difficult to maintain consistently. The main distinction for cataloguing purposes should therefore remain between Brazilian Portuguese and Portuguese.

4.1.4 Multilingual Editions

Some books, particularly poetry collections and translated works, include both the original text and its translation.

In these cases, tag the book with the language it has been translated into, rather than the language of the original text.

The title and/or synopsis will usually indicate that the original text is included, while readers are most likely searching for the language they can read.

Examples:

The book Selected Poems of Victor Hugo: A Bilingual Edition containing the original French poems alongside an English translation should be tagged as english.

A bilingual edition containing the original English drama The Taming of the Shrew by William Shakespeare alongside a German translation should be tagged as german.

4.1.5 Romanisation

When adding books or authors whose names use a non-Latin writing system without an official English or romanised spelling, use the standard romanisation system for that language.

Examples include:

Here is how it may look like in practice for the above:

Chinese
Title: 红楼梦 (Hónglóu Mèng)
Author: 曹雪芹 (Cáo Xuěqín)

Korean
Title: 채식주의자 (Chaeshikjuuija)
Author: 한강 (Han Gang)

Japanese
Title: 人間失格 (Ningen Shikkaku)
Author: 太宰治 (Dazai Osamu)

Arabic
Title: ثلاثية القاهرة: بين القصرين (Ṯulāṯiyyat al-Qāhirah: Bayn al-Qaṣrayn)
Author: الطيب صالح (Aṭ-Ṭayyib Ṣāliḥ)

For these books, format the metadata as follows:

Example: 红楼梦 (Hónglóu Mèng) by Cáo Xuěqín

Note: These romanisation rules apply to general books and authors. Manga and web novels may follow different naming and title conventions. For these types of books, please refer to the Manga Guide for the correct approach.

4.1.6 Original Date of Publication

The original date of publication refers to the year when a book was first published as a complete book, regardless of its original language.

If a book was initially published in serial form, do not use the year the serialisation began. Instead, use the year the complete book was first published.

Examples:

The Catcher in the Rye
First serialised: 1945
Published as a novel: 1951
Original Publication Year: 1951

The Metamorphosis
First published in original language (German): 1915
First English translation: 1933
Original Publication Year: 1915

For serialised series, use the publication year of the specific volume, not the year when the first chapter of the volume or the overall series was serialised.

Example:

One Piece, Vol. 2
First chapter of the volume (Chapter 9) released: 1997
Published as a tankōbon volume: 1998
Original Publication Year: 1998

Remember: The original publication date should represent the first release of the complete book or volume, not the beginning of its serialisation or the release date of a translation.

4.1.7 Editors and Contributors

For books where one or more editors are responsible for compiling or overseeing the work (such as anthologies, essay collections, poetry collections and many textbooks):

This follows the standard used by most major book platforms and helps accurately represent the role of each person involved in the work.

4.1.8 Self-Published Books

If a book is self-published or independently published, and the author is not publishing under the name of an established publishing company, enter Self Published in the Publisher field.

4.1.9 Study Guides and Companion Books

Study guides, annotated editions and companion books (such as SparkNotes editions) should be added as separate books, not as editions of the original work.

These publications often contain significantly different content and should be treated as their own entries.

4.1.10 ISBN Formatting

For Annotate, always use ISBN-13 when available. Do not include hyphens, spaces or dashes in the ISBN.

4.1.11 Audiodramas

For categorisation purposes, all audiodramas should be classified as audiobooks.

4.1.12 Comics vs Manga Titles

Comic books do not necessarily follow the same title rules as mangas.

For collected comic volumes, use the format: Title, Vol. 1
For single issue comics, use the format: Title #1

Example:

Star Trek: The Last Starship #1
→ The first comic issue in the Star Trek: The Last Starship series

Star Trek: The Last Starship, Vol. 1
→ A collection containing issues 1-6 of the Star Trek: The Last Starship series

Always differentiate between individual issues and collected volumes, as they represent different types of publications.

4.1.13 Adding Editions

When adding a new book with multiple editions, you do not need to add every edition immediately.

As a general rule, adding the following editions is sufficient:

Additional editions can be added later if requested by users.

4.1.14 Building the Database Through Editions

While we currently use OpenLibrary as a source for building the database, it will eventually become obsolete.

When correcting information from an OpenLibrary edition, if you have the time, consider adding an edition that matches the corrected book information. This helps build a more accurate database and reduces reliance on external sources in the future.

4.1.15 Unable to Use Custom Edited Editions as Featured Editions

Due to OpenLibrary limitations, we are currently unable to have custom-edited editions as the featured edition of a book (the book showing up when a user searches for it in app).

Because of this, it is important to keep all editions as complete and accurate as possible. Once OpenLibrary is no longer used as the primary source, this limitation will no longer apply.

4.1.16 Handling Completed Tickets

You do not need to send a reply every time you complete a user's request.

4.1.17 Handling User Tickets for Specific Book Editions

When a user requests that a specific edition of a book be added or edited, always verify that you are working on the correct edition.

4.2 Genre Selection

Genres help users discover books and organise their libraries. To ensure consistency across the database, always use the approved genre list.

4.2.1 General Guidelines

You can only select genres from our approved genre list.

In the future, we may introduce a tag system for subgenres and more specific classifications. Until then, you can only use the approved genres.

4.2.2 Fiction and Nonfiction

Every book in the database must be assigned either Fiction or Nonfiction.

These act as the primary genres and should always be included. They appear first in the genre list, while all other genres are displayed alphabetically.

4.2.3 History vs Historical

Be careful not to confuse the History and Historical genres.

Examples:

The Rise and Fall of the Third Reich → Nonfiction, History

The Book Thief → Fiction, Historical

4.2.4 Choosing the Correct Genres

If you are unsure which genres to assign, use the following sources in order of priority:

  1. StoryGraph - Preferred source, as their genres are based on publisher-provided information.
  2. Goodreads - Generally reliable, although genres are user crowd-sourced.
  3. Publisher website - Use the publisher's categorisation when additional confirmation is needed.
When in doubt, ask! If you're still unsure which genres to select, ask another librarian for a second opinion. We'd rather discuss a book than categorise it incorrectly.

4.3 Author Aliases

The Author Alias field is used when a book was published under a different name than the author's primary name. This includes pen names, pseudonyms and alternate publishing names.

Using the Author Alias field correctly ensures that readers can find all of an author's books in the app, while still accurately displaying the name under which each book was published.

A one-way link is used when books published under an alias should appear under the author's primary name, but books published under the primary name should not appear under the alias.

This is most commonly used for pseudonyms.

Example: Marissa Meyer → Amerie

Author: Amerie

Author Alias: Marissa Meyer

This means:

This approach should be used whenever the alias represents a separate publishing identity that readers would not normally expect to contain the author's entire bibliography.

A two-way link is used when an author is openly known to publish under two different versions of their name, and readers would reasonably expect to find the complete bibliography under either name.

In these cases, books published under either name should appear on both author pages.

Examples:

  • V.E. Schwab ↔ Victoria Schwab
  • R.F. Kuang ↔ Rebecca F. Kuang

To achieve this:

  • Books published as V.E. Schwab should have Victoria Schwab in the Author Alias field.
  • Books published as Victoria Schwab should have V.E. Schwab in the Author Alias field.

Likewise:

  • Books published as R.F. Kuang should have Rebecca F. Kuang in the Author Alias field.
  • Books published as Rebecca F. Kuang should have R.F. Kuang in the Author Alias field.

This means:

All books appear under both names, regardless of which name they were originally published under.

Note: The Author field should always contain the name that appears on the cover of the book. The Author Alias field is only used to create the desired connection between author profiles in the app.

5. Manga Guide

Please refer to this guide for correct approaches when adding or editing Manga and Web Novel titles.

6. Special Cases

6.1 Series Numbering Guidelines

Most books in a series will have a whole-number position (e.g. #1, #2, #3). However, there are a few special cases where a different numbering system should be used.

6.1.1 Prequels

Prequels should be numbered before the first main book in the series.

Example:

Among the Burning Flowers → #0.5

The Priory of the Orange Tree → #1

Using #0.5 makes it clear that the book should be read before Book 1 while keeping the main series numbering intact.

6.1.2 Split Translations

Sometimes a translation divides a single book into multiple volumes, even though the original edition was published as one book.

Example:

Book C (original edition) → #1

Book A (French Part 1) → #1a

Book B (French Part 2) → #1b

In these cases:

This allows users to find the translated volumes in the app while keeping the series page clean and displaying only the original book (#1).

6.1.3 Split Physical Editions

Some publishers divide a single novel into two physical books without changing the story. These should be handled the same way as split translations.

Example:

A Song of Ice and Fire Book 3:

A Storm of Swords: Steel and Snow → #3a

A Storm of Swords: Blood and Gold → #3b

As with split translations:

6.2 Additional Rule for Split Translations

As discussed, in some cases, a translation divides a single novel into multiple published volumes. These volumes should be added as separate books in the database.

If the split volumes belong to a single original book, they should also be linked together in their own series, named after that book.

Example:

البؤساء (Arabic translation of Les Misérables) was published in five separate volumes.

If the original book is also part of a larger series, continue following the Series Numbering Guidelines for numbering.

Creating a separate series for the split translation allows users to easily navigate between the individual translated volumes while maintaining the correct relationship to the original work and its parent series.

6.3 Chinese Books and Translations

6.3.1 Raws

If the book is in Chinese (raw), it should be titled as:

Example (JJWXC/Changpei Raw):

Title: 某某 (Mou Mou)
Author: 木苏里
Alias: Musuli
Language: chinese

6.3.2 Physical Editions (Raws)

For physical editions of raws:

Example:

Title: 某某
Author: 木苏里
Alias: Musuli
Series: 某某
Language: chinese

Note: Simplified Chinese editions are different from Traditional Chinese editions. They have different publishers, ISBNs, titles and laws. It's better to indicate this because it is also listed on official bookstore listings.

6.3.3 Fan Translations (Not MTL!)

Only use authorised fan translations! An authorised fan translation means:

For fan translations:

Example:

Title: 某某 A Certain Someone
Author: Musuli
Alias: 木苏里
Language: english
Contributor: Mimi (Translator)
Publisher: Chrysanthemum Garden

6.3.4 Official Translations

For official translations:

Example:

Title: A Certain Someone (Novel) Vol. 1
Author: Musuli
Alias: 木苏里
Language: english

6.3.5 Additional Notes

The romanised names for Chinese authors are used in the English publishing industry. This helps readers differentiate the English translated works from raws.

Merging: Don't merge the official translation to the raws if the official translation will be split into multiple volumes.

7. Continuous Improvement

7.1 Proactive Cataloging

Don't just wait for tickets. We need help expanding the database, particularly for books originally published in or popular in other languages, especially ones that don't have an English translation yet. Those are the works most likely to be missing from us entirely.

A good workflow is to pull up a popular Goodreads list (especially in a language you speak natively), search our Portal for the top titles, and manually add any that we are missing. Ensure they have good covers and accurate synopses.

Before adding, check whether the work is already here under its English title. If it is, the version you found is an edition of that book, not a new one. Only genuinely absent works get added as new books, and if a work does have an English translation, title it in English even when you found it on a foreign-language list.