As other child comments have stated, this is entirely subjective, and many would disagree with you (myself included). I live primarily in the terminal, and the ability to seamlessly look up syntax, flags, features, etc. without ever leaving the keyboard is wonderful. Additionally, I agree with milesrout that I do not want emoji, animations, etc. in my manuals (nor my terminal). I want searchable text. I also agree with lupusreal that having a single large page, at least as an option, is ideal.
A perfect example of the two approaches is HAProxy. Here [0] is their commercial site. It's very flashy, modern web, etc. I don't necessarily hate it, but it's definitely designed to get the attention who may not necessarily know what they want, and can be sold to. In comparison, here [1] is their community site. It is extremely Web 1.0, and I love it. Everything you need, nothing you don't. Similarly, their docs [2] are [3] logically [4] split, and manage to be readable, navigable, yet information-dense. I don't need a tutorial with code snippets every few paragraphs in my docs.
> Additionally, developers are very much used to markdown, and most other docs are written in markdown (maybe some RST, but probably mostly markdown) so this is not great for the person writing the docs either.
Web devs, perhaps, though I imagine there's more variety than you think. Kernel devs likely do not have the same opinion as you (though I do not wish to speak for them, as I am not a kernel dev). I've seen the same argument against the build and packaging process for Linux distros, like Debian. "Why is so much of this in Perl," "why are there so many bash scripts," etc. Because that is what the original developers wrote it in, it works well, and at this point is largely bug-free. Drastically changing something to suit the tastes of some at the risk of introducing errors is not a reasonable strategy.
I am a kernel dev and you've captured my thoughts on the matter quite well. I would very much rather stick with man, even with the deficiencies the article discusses, than use markdown and web.
It doesn't have to be either/or. You can generate a rich format to mdoc. I'm not completely convinced markdown isn't sufficient, but it doesn't have to be markdown.
As other child comments have stated, this is entirely subjective, and many would disagree with you (myself included). I live primarily in the terminal, and the ability to seamlessly look up syntax, flags, features, etc. without ever leaving the keyboard is wonderful. Additionally, I agree with milesrout that I do not want emoji, animations, etc. in my manuals (nor my terminal). I want searchable text. I also agree with lupusreal that having a single large page, at least as an option, is ideal.
A perfect example of the two approaches is HAProxy. Here [0] is their commercial site. It's very flashy, modern web, etc. I don't necessarily hate it, but it's definitely designed to get the attention who may not necessarily know what they want, and can be sold to. In comparison, here [1] is their community site. It is extremely Web 1.0, and I love it. Everything you need, nothing you don't. Similarly, their docs [2] are [3] logically [4] split, and manage to be readable, navigable, yet information-dense. I don't need a tutorial with code snippets every few paragraphs in my docs.
> Additionally, developers are very much used to markdown, and most other docs are written in markdown (maybe some RST, but probably mostly markdown) so this is not great for the person writing the docs either.
Web devs, perhaps, though I imagine there's more variety than you think. Kernel devs likely do not have the same opinion as you (though I do not wish to speak for them, as I am not a kernel dev). I've seen the same argument against the build and packaging process for Linux distros, like Debian. "Why is so much of this in Perl," "why are there so many bash scripts," etc. Because that is what the original developers wrote it in, it works well, and at this point is largely bug-free. Drastically changing something to suit the tastes of some at the risk of introducing errors is not a reasonable strategy.
[0]: https://www.haproxy.com
[1]: https://www.haproxy.org
[2]: https://docs.haproxy.org/3.1/intro.html
[3]: https://docs.haproxy.org/3.1/configuration.html
[4]: https://docs.haproxy.org/3.1/management.html