[neilv]

Agreed. For me, the popularity of Markdown on (pre-Microsoft) GitHub and GitLab was all I needed, to declare that the company wiki, code-embedded API docs, and anything else appropriate should just use Markdown.

Markdown is good enough for most of the documentation that software engineers do (other than diagrams), they already have to know it, and I don't want yet-another-markup-language to be a barrier to capturing and communicating institutional knowledge.

I also tell people that, if you're new to Markdown, even a plain text approximation that doesn't quite format correctly is strongly encouraged, so long as they capture the info somewhere accessible. I'll even offer to cheerfully fix the missing/bad Markdown, so that we have working docs and people can learn the very few parts of Markdown they missed; it's really not much.

(I personally have heavily used many much-much better technical documentation systems, and helped develop a WYSIWYG-ish SGML-based one professionally, but just using Markdown is a no-brainer right now. There are much more important things I want people learning and doing, than N different ways of minimally formatting documentation in N different places.)

[jve]

> other than diagrams

Works fine with some help https://mermaid.live/ https://github.blog/developer-skills/github/include-diagrams...

[haiku2077]

No, mermaid is not fine. You don't have fine control over layout and composition, you can't place your own media and annotations where you like, you can't even use the correct icons for things like databases and cloud services. I usually go into Figma for anything more complex than about 7 entities or if I need to tell a story with composition.

[touisteur]

A mix plantuml for constrained no-frills diffable standard diagrams and yEd for actual manual placement and boxes-and-arrows drawing - local editing, both can be scripted to export to an image format - is a good local optimum. I haven't found a much better combination for years.

[pottertheotter]

I agree. I use markdown a lot and was trying to use Mermaid for diagrams in it and it was frustrating. Among the biggest issues I ran into was that text was constantly cut off or covered up.

[1bpp]

Is there a reason you specify pre-Microsoft GitHub?