Decision: Where should the embedded books live?

[jamesmunns]

We had an offer from @steveklabnik to host any of the embedded books we would like on the official doc.rust-lang.org bookshelf.

Pros:

• Greater visibility
• Makes embedded look more official
• Books become available offline, as they are distributed through rustup

Cons:

• Book update process requires a manual PR to update
• If we have duplicate copies between docs.rust-embedded.org and doc.rust-lang.org, thats probably bad for SEO, and might cause confusion.

In IRC, we came up with the following possible solutions:

1. Move all embedded books, even the not-so-polished ones, to doc.rust-lang.org
2. Keep all books only on docs.rust-embedded.org
3. Move only "the book" to doc.rust-lang.org, treat docs.rust-embedded.org as "the embedded docs nursery"
4. Host docs in both places

[adamgreig]

We could also see if we can have a link to the rust-embedded bookshelf from the rust-lang bookshelf? I don't know how that interacts with offline copies via rustup.

[steveklabnik]

Anything not in the main rust repo does not get distributed offline.

[adamgreig]

@steveklabnik but can the docs link to online content which is not distributed offline? Would it be OK to have a link to our online bookshelf inside the offline docs?

[steveklabnik]

We can technically, but it's a frustrating experience for users, so we try not to as much as possible. I would prefer to not except in extremely extenuating circumstances, of which I don't think this is.

[adamgreig]

That's fair and sort of what I expected, thanks for clarifying!

[Ravenslofty]

I think 3) is best; having the book in docs.rust-lang.org gives it an "official" air, so it should be good quality. It also attracts more eyeballs, which is useful for attracting attention.

[jamesmunns]

Yeah @ZirconiumX, I agree. My vote would be 3), with a link to the doc.rust-lang.org copy of the book on our landing page. This way we still have the "landing page" which points to all the books in one place, and by then, the users probably don't care whether the links take them to docs.rust-embedded.org/book or doc.rust-lang.org/embedded-book/

[jamesmunns]

Hey @rust-embedded/all - if no issues are raised, I would like to go with the following plan:

1. Open a PR to the upstream doc repo adding the Embedded Rust Book as a submodule there
2. Change the link on https://docs.rust-embedded.org/ to point to https://doc.rust-lang.org/embedded-book/ (or whatever path @steveklabnik would suggest) for the "Embedded Rust Book"
3. Update the new website (not yet public) to point links to the "centralized" copy of the book
4. Add a robots.txt to our copy of the book (https://docs.rust-embedded.org/book/), preventing it from being crawled.
5. Replace all current pages of https://docs.rust-embedded.org/book/ and children to be 300 redirects to the "centralized copy"
6. Rename our copy to something like https://docs.rust-embedded.org/nightly-book/ - to make it clear what the purpose of this copy is. Still with an aggressive robots.txt to prevent search engines finding it

If there are no objections, I'd like to start this process by the end of this week, so if you have concerns, please raise them early so we can address them quickly (or come up with another plan).

Edit: I believe this meets our goal of the following:

• Centralized place for finding embedded docs - https://docs.rust-embedded.org/ - this page will still link to all books, whether they are hosted "here" or "there"
• We get the "official" looking presentation of our book being with the rest of the books
• Our book gets distributed for offline consumption
• We have a path for migrating other books in the future
• We still have a nightly build of our book for review, and can use it in a pinch

[jamesmunns]

I will begin implementing this as there have been no objections. Implementation checklist:

• PR upstream - (EDIT: In progress, see Initial addition of the Embedded Rust Book rust-lang/rust#56291)
• Change docs landing page
• Update new website links
• robots.txt the old book location
• 300 redirects for the old book
• rename nighly version of the book, with robots.txt

[nickray]

Why do the docs live under docs.r-e.org when docs.r-l.org redirects to doc.r-l.org (which I guess is being copied here)? At least a redirect from doc.r-e.org would make sense :)

[jamesmunns]

@nickray there was a voting issue where we picked the name, IIRC docs beat out doc fairly soundly. I think opening an issue to implement the doc => docs redirect would make sense, @nastevens where should that issue go?