Should I keep a separate Sphinx docs branch or switch to MkDocs?

[PaulQW]

I’m trying to decide if it’s worth maintaining a separate branch of our project’s documentation that’s built with Sphinx, or if we should just force everyone to use the main branch’s MkDocs setup. The duplication feels messy, but I also hate the idea of leaving behind contributors who are deeply familiar with the old toolchain and its specific workflows.

[GregoryL]

We tried keeping both doc branches and it bogged us down. Every release there was a mismatch and someone had to patch two sites. After a few cycles we dropped the separate branch and kept one pathway for updates with a clear deprecation plan.

[MilaG]

I know some folks still lean on the old Sphinx workflow. If we go single path we could offer a small isolated guide for the people who want to stay in the old flow and a simple migration path for new contributors.

[Kyle23]

Maybe the real pain is our review pace not the docs format Do we need a better review process or better tooling?

[Dennis.J]

We ran a two week pilot moving all content to one site and kept the old topics in a lightweight compatibility layer. The publishing time dropped by roughly one day per release and it cut confusion in the team a bit.