Hacker News Reader

Comment by Veen | Hacker News Reader

They explain the difference in an 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.

View on HN

I like that they write it as a trade of. I think I still prefer the maintainability complications of "docs as code" https://www.youtube.com/watch?v=xEu3t-KJVVg

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.

Docs Like Code, Anne Gentle, p. 10

The quoted text says "as" and clearly intends that meaning.

Ah, thank you for the term in question. Found a relevant link: https://www.writethedocs.org/guide/docs-as-code/

"There is a lot more to building a proper Docs as Code workflow. There are a couple books we recommend that you check out:

    Docs Like Code - Anne Gentle
    Modern Technical Writing - Andrew Etter
"

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.

> Markdoc uses a fully declarative approach to composition and flow control, where MDX relies on JavaScript and React.

This doesn't make sense to me? React is also a "fully declarative approach to composition and flow control".

> content can quickly become as complex as regular code

Okay, but has that actually happened in practice?

> React is also a "fully declarative approach to composition and flow control".

MDX, which allows embedding JSX isn't fully declarative, since arbitrary imperative structures can be used in JS blocks in JSX.

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.

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.

> 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.)

[0] https://stripe.com/docs/payments/quickstart

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

Not Markdoc, but there are several OSS examples of how you can do something similar with MDX + Code Hike. https://codehike.org/

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?

Reply on news.ycombinator.com