diff --git a/docs/README-migration.md b/docs/README-migration.md
index 26bf217841..2f00a5d704 100644
--- a/docs/README-migration.md
+++ b/docs/README-migration.md
@@ -4,6 +4,8 @@ This guide provides useful information for migrating applications from SDL 2.0 t
 
 Details on API changes are organized by SDL 2.0 header below.
 
+The file with your main() function should include <SDL3/SDL_main.h>, as that is no longer included in SDL.h.
+
 Many functions and symbols have been renamed. We have provided a handy Python script [rename_symbols.py](https://github.com/libsdl-org/SDL/blob/main/build-scripts/rename_symbols.py) to rename SDL2 functions to their SDL3 counterparts:
 ```sh
 rename_symbols.py --all-symbols source_code_path
@@ -11,14 +13,11 @@ rename_symbols.py --all-symbols source_code_path
 
 It's also possible to apply a semantic patch to migrate more easily to SDL3: [SDL_migration.cocci](https://github.com/libsdl-org/SDL/blob/main/build-scripts/SDL_migration.cocci)
 
-
 SDL headers should now be included as `#include <SDL3/SDL.h>`. Typically that's the only header you'll need in your application unless you are using OpenGL or Vulkan functionality. We have provided a handy Python script [rename_headers.py](https://github.com/libsdl-org/SDL/blob/main/build-scripts/rename_headers.py) to rename SDL2 headers to their SDL3 counterparts:
 ```sh
 rename_headers.py source_code_path
 ```
 
-The file with your main() function should also include <SDL3/SDL_main.h>, see below in the SDL_main.h section.
-
 CMake users should use this snippet to include SDL support in their project:
 ```
 find_package(SDL3 REQUIRED CONFIG REQUIRED COMPONENTS SDL3)
@@ -39,10 +38,7 @@ LDFLAGS += $(shell pkg-config sdl3 --libs)
 
 The SDL3test library has been renamed SDL3_test.
 
-There is no SDLmain library anymore, it's now header-only, see below in the SDL_main.h section.
-
-
-begin_code.h and close_code.h in the public headers have been renamed to SDL_begin_code.h and SDL_close_code.h. These aren't meant to be included directly by applications, but if your application did, please update your `#include` lines.
+The SDLmain library has been removed, it's been entirely replaced by SDL_main.h.
 
 The vi format comments have been removed from source code. Vim users can use the [editorconfig plugin](https://github.com/editorconfig/editorconfig-vim) to automatically set tab spacing for the SDL coding style.
 
@@ -699,27 +695,6 @@ Instead SDL_main.h is now a header-only library **and not included by SDL.h anym
 Using it is really simple: Just `#include <SDL3/SDL_main.h>` in the source file with your standard
 `int main(int argc, char* argv[])` function.
 
-The rest happens automatically: If your target platform needs the SDL_main functionality,
-your main function will be renamed to SDL_main (with a macro, just like in SDL2),
-and the real main-function will be implemented by inline code from SDL_main.h - and if your target
-platform doesn't need it, nothing happens.
-Like in SDL2, if you want to handle the platform-specific main yourself instead of using the SDL_main magic,
-you can `#define SDL_MAIN_HANDLED` before `#include <SDL3/SDL_main.h>` - don't forget to call SDL_SetMainReady()
-
-If you need SDL_main.h in another source file (that doesn't implement main()), you also need to
-`#define SDL_MAIN_HANDLED` there, to avoid that multiple main functions are generated by SDL_main.h
-
-There is currently one platform where this approach doesn't always work: WinRT.
-It requires WinMain to be implemented in a C++ source file that's compiled with `/ZW`. If your main
-is implemented in plain C, or you can't use `/ZW` on that file, you can add another .cpp
-source file that just contains `#include <SDL3/SDL_main.h>` and compile that with `/ZW` - but keep
-in mind that the source file with your standard main also needs that include!
-See [README-winrt.md](./README-winrt.md) for more details.
-
-Furthermore, the different SDL_*RunApp() functions (SDL_WinRtRunApp, SDL_GDKRunApp, SDL_UIKitRunApp)
-have been unified into just `int SDL_RunApp(int argc, char* argv[], void * reserved)` (which is also
-used by additional platforms that didn't have a SDL_RunApp-like function before).
-
 ## SDL_metal.h
 
 SDL_Metal_GetDrawableSize() has been removed. SDL_GetWindowSizeInPixels() can be used in its place.