add instructional help text to book-edit page

jzacsh commented 1 year ago

Is your feature request related to a problem? Please describe.

A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]

Problem: it's unclear what exactly a "goodreads key" is in the new input field when editing a book.

More broadly, the entire edit page might really benefit from some directed guidance on how to think about some of the fields on a given listing.

Describe the solution you'd like

A clear and concise description of what you want to happen.

It'd be great if the edit page described some basics about editing a book. things I think would be helpful:

a tiny overview explaining most systems (including bookwyrm) distinguishes a general work versus a specific version of that work.
a specific overview under the "Book Identifiers" section giving a quick primer on being thoughtful about changes (eg: going to change an existing ID? maybe only do that if there's an no other bookwyrm-reviews/bookwyrm-lists attached to this "listing" (or whatever bookwyrm-noun/jargon bullet 1 established).
for each identifier, a tiny bit of help text below the input field. at the least a URL (eg: for isbn I think isbn13 could just be the URL to isbn's wikipedia entry, whereas maybe isbn10 could be something like "if isbn13 is present, this field is superfluous")

Describe alternatives you've considered

A clear and concise description of any alternative solutions or features you've considered.

Alternatively, just tackle a subset of the tasks I'm describing: just do bullet 3 above only for the "goodreads key".

The content for this particular smaller task would be something like the following (according to this thread):

Goodreads key is what Goodreads APIs call a "book_id" - their stable identifier for a given edition. The book_id is usually found embedded in that edition's URL. Goodreads doesn't document this clearly anywhere but as of 2023-04 we can say it shows up as an integer coming right after the string /book/show/ (for example given the URL https://www.goodreads.com/book/show/3899622-hands-of-m your the "key" we store here in bookwyrm would be 3899622).

pro: a quicker solution, and we'd need less consensus and writing needed
con: without the bigger-picture explanation (like bullet 1), folks might be encouraged by this text and not cautioned from confusing editions. eg: a person might easily see an empty goodreads key, and paste the one in there that they have in their own account, without looking at the potentially different ISBN present already on this bookwyrm listing (for which the correct goodreads key is probably different). tl;dr maybe this will corrupt the quality of bookwyrm listings :|

Additional context

Add any other context or screenshots about the feature request here.

I personally think this broader topic (book IDs, versions and works, and how each system uses different jargon for nearly-identical facets) can be very confusing and not-obvious. In case it helps the discussion here, I've posted some old notes I took on the topic, here: https://daxo.dev/book-ids#EstablishedIdentifiers

jzacsh commented 1 year ago

I'd be happy to do the work here and write up the new help-text. But I'd want to:

a) be sure @mouse-reeve actually wants this change to land
b) get some guidance: is there de facto language for this in bookwyrm(code+uis) that I could/should reuse? mainly for editions/works distinction; see bullet 1 above.

mouse-reeve commented 1 year ago

I'm definitely pro-this! More clarity is good. The format and format detail field is another place a little extra clarity would help. We've been using a pattern in the UI with aria-described-by attributes with the help class from the css library, like so, from the user preferences page:

<div class="field">
    <label class="checkbox label" for="id_discoverable">
        <input type="checkbox" name="discoverable" aria-describedby="desc_discoverable" class="checkbox" id="id_discoverable" checked="">
        Show this account in suggested users
    </label>

    <p class="help" id="desc_discoverable">
        Your account will show up in the <a href="/directory">directory</a>, and may be recommended to other BookWyrm users.
    </p>
</div>

haheute commented 1 year ago

I am also wondering, what the goodreads key is.. I have added the 'id' number from the book's url: 27543121 (from this URL: https://www.goodreads.com/book/show/27543121-ambition-to-vision )

mouse-reeve commented 1 year ago

Yes, that is what is

bookwyrm-social / bookwyrm