> The key difference is that MDX supports arbitrarily-complex JavaScript logic (think: docs as code) while Markdoc enforces a strict separation between code and content (think: docs as data).
> Markdoc uses a fully declarative approach to composition and flow control, where MDX relies on JavaScript and React. This means MDX affords users more power and flexibility, but at the cost of complexity–content can quickly become as complex as regular code, which can lead to maintainability complications or a more difficult authoring environment.
Just a gentle reminder that docs like code has an actual definition that we can refer to.
When we say treat the docs like code, we mean that you:
* Store the doc source files in a version control system.
* Build the doc artifacts automatically.
* Ensure that a trusted set of reviewers meticulously review the docs.
* Publish the artifacts without much human intervention.
That's not how language works, their phrase (that does not actually have a widely used established meaning) means what they meant, not what you say it means.
Yes, that term does have a widely established meaning within the specific context of discussion, technical writing. If the commentator is unaware of what 'docs as code' means in the context under discussion and meant something different, I encourage them to disambiguate by picking a term not already so defined.
> Okay, but has that actually happened in practice?
Before we built Markdoc, our documentation was powered by ERB (embedded Ruby templates). Having content mixed with arbitrary code made it incredibly hard to reason about either. Because Markdoc is a declarative language rather than imperative, there's no intermediate state to keep track of, making things easier to follow.
At Stripe, both engineers and tech writers contribute to documentation. Markdoc makes things easier for everyone by keeping the content separate from the code, while still making it possible to build more interactive experiences when you want to. (For example, our integration builder [0] is also powered by Markdoc.)
Quick question. How do engineers and tech writers use the "live editor" functionality that seems to be in the open source repo? Do you edit in the live editor and is it set up to update the underlying repo? Or do you just modify the markdoc files in the repo with your own editor?
I am a huge fan of this style of page! is there an OSS example of this in full? I would be very keen to see what goes into making such a dynamic page in markdoc looks like
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.
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.
https://markdoc.io/docs/faq
> The key difference is that MDX supports arbitrarily-complex JavaScript logic (think: docs as code) while Markdoc enforces a strict separation between code and content (think: docs as data).
> Markdoc uses a fully declarative approach to composition and flow control, where MDX relies on JavaScript and React. This means MDX affords users more power and flexibility, but at the cost of complexity–content can quickly become as complex as regular code, which can lead to maintainability complications or a more difficult authoring environment.