added discovery book triage RFC

[BartMassey]

This RFC proposes a plan for triaging the Rust Embedded Discovery Book (collection).

[BartMassey]

This RFC needs a bit of work to be accurate. Please give me a few minutes to get things corrected and completed.

Apologies.

[BartMassey]

That's better. Feedback welcome.

[eldruin]

Comment from @sirhcel:

As this discussion started here, I'd like to bring over my thoughts for today's meeting.

What do you see as the benefit from having a separate repo? If it is about just archiving the contents for the micro:bit V1 and the STM32F3 (#567 which i would like to address here as well) what about keeping it in this repo under a certain tag or branch? We could mention this briefly in a note on previous versions of the book.

To me a more prominent question would be whether to keep the rendered version of the current book online. This looks somewhat charming to me:

• Existing links would not break
• This would not confront people on this journey having already some cognitive load with hitting a HTTP 404 "wall"
• We could add a note on each page for guiding them gently to the new version of the book

Have we decided about how to maintain the current version of the book yet? A complete freeze still fixing grave things? The latter would not include keeping the documentation up to the latest versions of tooling.

How to deal with the currently open issues and PRs? What about using note or issue template for pointing out that the current version is about to be deprecated soon and stating the policy on maintaining the old version to set some expectations for contributors? What about closing current issues and PRs once the upcoming update made some significant progress?

[eldruin]

Thank you for writing this up.
I agree with the concerns stated above by @sirhcel. I am especially concerned about a 404 wall and would rather like to see some kind of redirection.
Regarding repository splitting, I would say that that would make it more difficult to keep a version of EDB-STM online to avoid said 404 wall. A tag in the repo would be simpler in my view.

I would prefer to fill the EDB-MB2 (only for MB2, we already have a chapter like that where MB1 is not supported) with the missing EDB-STM content before doing any archiving of EDB-STM.
Otherwise, I see a risk of throwing out valuable content and never actually porting it as there is always too much stuff to do.

I am fine with just removing support for MB1 and say that MB2 is a requirement.

[9names]

I think saying they'll "feel disenfranchised" is quite hyperbolic?
We aren't depriving them of rights, anyone with a STM32F3V303 or MB1 can still can still follow the existing docs.

[eldruin]

The drawback is that if the STM and/or MB1 versions of the books are removed, then they cannot follow them.

[9names]

There's no mention of removing existing books in this RFC

[sirhcel]

Couldn't we just keep the existing books hosted/published and "watermark" them to guide to the maintained version for the mico:bit v2? For those who dare to look at the repository, a note in README.md could provide guidance for in which branches/tags to find the old sources.

[BartMassey]

"Disenfranchised" was surely the wrong word to use here. But I suspect that there are people who want to continue using and teaching with the STM Discovery Board who will be unhappy that we won't be maintaining that book for them.

I thought about keeping the offer for someone to maintain EDB-STM open; if the right person came along to do that I'd be happy to talk to them. But I think it would take a concerted maintenance effort coordinated with the EDB-MB2 effort to keep that book going.

[BartMassey]

I absolutely plan to keep all current book content available indefinitely, even in unmaintained form. I don't see any upside to removing it, and a lot of downside. This RFC is purely about restructuring, catching up maintenance, and establishing some base that can be readily maintained.

[CodingInGreen]

As a newbie about 6 months ago, I headed into the Embedded Rust matrix channel asking questions on where to start. It was recommended to start with the micro:bit V2 and the Discovery book for the V2, and I was provided the link. I'm not sure if I would have found the Discovery book and found that it would be right for learning embedded rust on my own without that guidance, by just searching the internet. So I think for a lot of newbies that might be path to how they find it, through the matrix channel and being provided the proper link to the new book we'll write. I think it's important we don't break links to the old resources, but I wouldn't be overly concerned about it, if it makes it cleaner and more straight forward for newbies to find the new Discovery Book information quickly and have success quickly so they don't lose interest.

[BartMassey]

These are all really useful comments, thanks.

• This RFC didn't really address what to do with the formatted books. I agree that it would be bad for anything widely referenced to 404; we will make sure that doesn't happen. I don't plan to republish the formatted books until the entirety of this RFC is complete. I think we can manage with the "landing page book" at the current location to separately publish EDB-STM when the time comes; maybe I'm missing a problem there?

  I am less concerned about splitting the repos: a note in the README should suffice there.

• The less-effort update of just removing MB1 content and leaving the repo as it is surely a viable option. The biggest problem I see there is that folks are going to continue to expect to be able to post STM issues and PRs against that repo. The split makes it absolutely clear that we aren't really doing that.

  My personal bias is against a monorepo: EDB-STM and EDB-MB2 are really seriously different books at this point, and I think it makes more sense to track changes and manage state separately. We could branch/tag EDB-STM and then remove it, but that seems to me to make the source harder to find rather than easier.

  All that said, I'm open to whatever folks prefer. Not having to do the repo splits and deal with the results is less work.

• We won't publish in any new way until this RFC is complete, including the step where we import the missing EDB-STM content to EDB-MB2. I put this step last only because I wanted to get a stable foundation down before doing this work.

Again, thanks for all the comments! I'm dealing with end-of-quarter at dayjob right now, so this is a good time to figure everything out while I still don't have a ton of time to put work into the actual work.

[eldruin]

Thank you @BartMassey. That addresses my concerns. I misunderstood the RFC.
I agree with the upsides of splitting the STM book into another repository. The publishing CI step would need some tweaking, though, so that we can push some content from one repo to another. (The discovery book is built and then the result is pushed to a gh-pages branch within the same repo. See here).

[BartMassey]

@eldruin I think I need to add a fourth step to the RFC for publishing, to make things clear. My plan was just to fix up the landing page book to point to an independent published EDF-STM on github.io and leave a link where EDF-STM sat previously. (I'd put a redirect if I could, but I can't see how that would be possible.) That would be easier than fixing up the auto-publishing, if you think that's OK?

If you're cool with these plans I'll go ahead and do some RFC updates and we can review again before merging?

Thanks for all your help!

[eldruin]

My plan was just to fix up the landing page book to point to an independent published EDF-STM on github.io and leave a link where EDF-STM sat previously.

That would lead to the mentioned 404 wall for all existing links but we can do some mitigations. It is generated by mdbook as well so have it under our own control (also, we should first make it look not totally broken). With some trivial javascript we could automatically redirect the user to the new address for the STM book (e.g. if /discovery/f3discovery in url, replace that with /f3discovery and go there).

If not doing some clever inter-repo publishing, we can do this:

1. Split the discovery repo and put only the f3discovery part in a rust-embedded/f3discovery repo
2. Adjust the CI there to publish itself under docs.rust-embedded.org/f3discovery
3. Add banners everywhere saying that it is outdated and unmaintained and where the new one is.
4. Archive that repo.
5. Add link to new url in landing page and note its status there
6. Improve 404 page saying things about the older STM book and where it is (for people without javascript on) and make it redirect STM urls with javascript
7. Remove STM stuff from the discovery repo

Opinions?

[BartMassey]

I'm not sure I understand the implications of the first plan. Are we trying to make every link into the old STM book not 404, or just the root link? If the first plan involves making a shadow of the book, then the second plan is definitely better.

How about we go with the second plan, and you help me with it when the time comes 😀? I'll try to revise the RFC to reflect all this, then have you look at it again.

[BartMassey]

Rewrote substantially. Please see #770 for the current version.