undefined | Better HN

0 pointsipsum24y ago0 comments

> 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?

0 comments

8 comments · 3 top-level

nkohari4y ago· 3 in thread

> 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

tdrhq4y ago

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?

nukemandan4y ago

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

pomber4y ago

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

Veen4y ago· 2 in thread

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.

docmechanic4y ago

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.

etchalon4y ago

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.

dragonwriter4y ago

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

j / k navigate · click thread line to collapse