Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Markdoc: Stripe's Markdown-based authoring framework

markdoc.io

Post reply on HN
Print view View original

141–150 of 157 posts

Re: Markdoc: Stripe's Markdown-based authoring framework

#141

Post by docmechanic »

maxerickson wrote: post #124
docmechanic wrote: post #117

Earlier quoted context omitted.

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.

Re: Markdoc: Stripe's Markdown-based authoring framework

#142

Post by pomber »

nukemandan wrote: post #134
nkohari wrote: post #38

Earlier quoted context omitted.

> 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 c…

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/

Re: Markdoc: Stripe's Markdown-based authoring framework

#143

Post by evolve2k »

armchairhacker wrote: post #85
_miau_hoch2 wrote: post #64

For anyone looking for a doc generation tool: I was lately evaluating several tools like VuePress, Docusaurus and AsciiDoc. I ended up using Mkdocs Material ( https://squidfunk.github.io/mkdocs-material/ ). If you haven't already, have a look. I think it is pretty impressive. From tags, tabs to the fantastic built-in search ...

After looking through Docusaurus, GitBook, and a few others, I also ended up with mkdocs and github pages. It’s very straightforward to setup.

I spent 6 months assessing the options came down to ‘Material for Mkdocs’.

Re: Markdoc: Stripe's Markdown-based authoring framework

#144

Post by jtbayly »

__mharrison__ wrote: post #135
jtbayly wrote: post #130

Earlier quoted context omitted.

Bookdown seems to support index entries: https://bookdown.org/yihui/bookdown/latex-index.html I wouldn't be surprised if Quarto supports the same syntax, since they are related. But it is possible it doesn't.

It might. I'm not interested in hacking R.

I'd be very interested in seeing your markdown (pandoc filter) based solution, if you can publish it.

Re: Markdoc: Stripe's Markdown-based authoring framework

#145

Post by cdevroe »

eek2121 wrote: post #131
cdevroe wrote: post #34

Earlier quoted context omitted.

I agree. Most companies, open source projects, and individual developers find this to be a Herculean challenge. I'd love to know if Stripe has any secrets to keeping their Docs updated. Though, my gut says that they likely just put in the work. Their Docs are incredibly important to their success.

I would describe stripe docs as 'acceptable'. Don't get me wrong, I personally have brought them tons of business and work with their API more than a human should. My only issue is that if you are working with their API, you will discover HUGE gaps if you step outside "the norms". That being said, they are a step above everyone else, which should tell you something. Also, the comment regarding open-source applies 300…

It seems that many Stripe team members walk the HN halls, if you were to give a few examples of the "HUGE gaps" you mentioned they might fill them in.

Re: Markdoc: Stripe's Markdown-based authoring framework

#147

Post by edwinwee »

cdevroe wrote: post #145
eek2121 wrote: post #131

Earlier quoted context omitted.

I would describe stripe docs as 'acceptable'. Don't get me wrong, I personally have brought them tons of business and work with their API more than a human should. My only issue is that if you are working with their API, you will discover HUGE gaps if you step outside "the norms". That being said, they are a step above everyone else, which should tell you something. Also, the comment regarding open-source applies 300…

It seems that many Stripe team members walk the HN halls, if you were to give a few examples of the "HUGE gaps" you mentioned they might fill them in.

Yes—would like to hear more about how we can fill in the gaps. (Can also email me directly at edwin@stripe.com.)

Re: Markdoc: Stripe's Markdown-based authoring framework

#148

Post by d4rkp4ttern »

_miau_hoch2 wrote: post #64

For anyone looking for a doc generation tool: I was lately evaluating several tools like VuePress, Docusaurus and AsciiDoc. I ended up using Mkdocs Material ( https://squidfunk.github.io/mkdocs-material/ ). If you haven't already, have a look. I think it is pretty impressive. From tags, tabs to the fantastic built-in search ...

Does Mkdocs have functionality to auto-generate docs from docstrings? I’ve been using Sphinx with RTD (ReadTheDocs) theme for python code. Wondering if Mkdocs can somehow be better.

Re: Markdoc: Stripe's Markdown-based authoring framework

#149

Post by d4rkp4ttern »

Does this have functionality to auto-generate docs from (python) docstrings? Currently using Sphinx with RTD (ReadTheDocs) theme for this, and quite happy with it, though the setup took a lot of hunting around for examples. Wondering if this is the best auto-doc approach for python these days. For context, I am developing a code base with the intention of later open sourcing it, so wanted to have it properly documented from the start.

Re: Markdoc: Stripe's Markdown-based authoring framework

#150

Post by tdrhq »

nkohari wrote: post #38
ipsum2 wrote: post #16

Earlier quoted context omitted.

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

> 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 c…

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?
Post reply on HN