The problem I have with this shift is that you basically give up on writing documentation by hand, not only for you, but for everybody who might want to edit your documentation.
I'm also not convinced that it solves meaningful problems :
> I've found I tend to not actually read more than a 100-line markdown file, and I certainly am not able to get anyone else in my organization to read it. But HTML documents are much easier to read, In my experience, LLMs are not concise when it comes to documentation, so using an easier file format to read because the text is too large sounds to me like solving the wrong problem
> Markdown files are fairly hard to share since most browsers do not render them natively well. Yes, but developers tools (IDE, Git forge) do. What most/some of them don't render natively IS HTML.
>I tend to not actually read more than a 100-line markdown file
I tend to not actually read more than 100-lines of anything anymore. I've long referred to myself as "the Google generation": only being able to read the summaries in a search result. That, and the typical doomscrolling model of social media have affected my attention span. Reading anything more substantial takes real effort now.
Writing and editing html by hand is very simple, it can be just a few basic tags.
>But HTML documents are much easier to read, [than markdown]
Presumably you mean rendered HTML rather than the source documents?