Re:Markdoc: Stripe's Markdown-based authoring framework
by Veen on Wednesday May 11, 2022 @11:57AM
(#31341797)
No idea, but it's worth keeping in mind that documentation isn't always written and edited by developers (because developers aren't always good writers). Maintaining the separation between code and content is a good idea if a company uses technical writers or other non-developer content people.
[ Parent
| on HN ]
Re:Markdoc: Stripe's Markdown-based authoring framework
by docmechanic on Wednesday May 11, 2022 @01:58PM
(#31343541)
An alternative point of view from Docs Like Code, p.11
Reasons we treat docs like code
Coders and writers have borrowed tools and techniques from each other for decades. When you look at the history of producing docs and code together, you see that tools were invented specifically to produce docs while coding.
For example, the JavaDoc tool has been available since the first Java release in 1999. Visualizing the code in HTML, providing accessible online docs, and updating the documentation with the code were all keys to its success.
Re:Markdoc: Stripe's Markdown-based authoring framework
by etchalon on Wednesday May 11, 2022 @02:40PM
(#31344060)
We handle this by having some components that don't require much training to use (<Note />, <Warning />, <Function />).
I don't think you have to choose between "can be powerful" and "can be simple."
If you want to lock things down so no one EVER puts code in your docs, Markdoc looks great.