Migration docs needs to guide more

[ocdtrekkie]

dale_price(at)mastodon.online offered up the following on Discord, and I felt it was really valuable:

This is just my anecdotal experience, but I had to use someone’s unofficial guide to migrating because the official docs at https://docs.joinmastodon.org/user/moving/ just sort of lists some migration-related things in isolation but doesn’t actually tell you how to do it, step by step, in order. (that page also says how to export your data but never says how to bring any of it to the new instance)

Likewise, the actual migration UI is split across two different pages (“account migration” and “account aliases”) with a lot of warning text but nothing that clearly says what order to do things in. Also required me to have both the old and new instance open in separate tabs and be careful not to do a step in the wrong tab, but there was no way to distinguish which instance was which in the UI itself, only by looking at the address bar

In some places the terminology is unclear, for example the migration page says "The new account must first be configured to back-reference this one”. Which account is “this one”? (what if I opened this page on the new instance by mistake, then I’d get it all backwards if I was following this instruction!) What is a "back-reference”? Is that the same as an alias? It says it has to be configured (by who? me? my server admin?) but doesn’t say how and isn’t clickable.

Personally I think the single biggest change that would have helped me, is if the pages were titled something like “Get ready to move to [instance name here]” and "Move from [instance name here]” instead of “Account migration” and “Account aliases"

https://codingitwrong.com/2022/10/10/migrating-a-mastodon-account.html is the guide that I found helpful, and includes a lot of steps that I think might have seemed obvious to the people who created the migration UI and official docs, but were absolutely not clear at all to me as someone who had been using mastodon for a while but not migrated before. E.g. I had no idea from the official docs that I would have to manually create the account on the destination instance and set up its profile details before starting migration, nor do I see any mention of that in the migration UI

I'm hoping maybe we could improve the migration documentation into a more clear guide for newer users, and maybe cut out some of the fear people have of doing account migrations. Perhaps the author of that guide would also be interested in directly contributing or being used as a source.

cc: @CodingItWrong

[CodingItWrong]

If anything written in my post is helpful, anyone please feel free to use it as-is or change it. I can update my post to point to future updated official migration docs in case of links still floating around.