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

111–120 of 157 posts

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

#111

Post by gpoore »

blutack wrote: post #23

Does anyone know of tooling like this but not for only making websites? I have an asciidoc based chain that mostly works for generating both PDF manuals and standalone html docs but it's a bit of a faff to install and set up especially for non-technical users. My dream is something like pandoc but with one or more diagram libraries integrated, native PDF output and all wrapped up in a single binary, maybe with a nice…

I've created a VS Code extension that provides a live Pandoc preview with scroll sync and support for executing code: https://marketplace.visualstudio.com/items?itemName=gpoore.c.... Adding support for diagrams would just be a matter of creating a config file specifying the diagram executable and command-line options.

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

#112

Post by clintonb »

cdevroe wrote: post #34
oellegaard wrote: post #32

Earlier quoted context omitted.

Would be very cool with some information on how they work with creating the docs, manage them etc.

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'd love to know if Stripe has any secrets to keeping their Docs updated.

Simple: documentation is part of the "definition of done". This goes for API docs (e.g., editing field descriptions) and integration guides/high-level docs. The feature/project isn't done if no one knows how to use it.

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

#113

Post by [deleted] »

oellegaard wrote: post #32
cdevroe wrote: post #26

Stripe's Docs have been best-in-class for a long time. Obviously, the care and human hours they put into their upkeep is the main reason for the Docs being so good. But, as with any creative endeavor, the tools matter. If the Stripe team didn't like the content management system they used to keep the Docs up-to-date they'd be less likely to do it. As someone that has used their Docs for hours and hours and hours I'm…

Would be very cool with some information on how they work with creating the docs, manage them etc.

[deleted]

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

#115

Post by aquilaFiera »

prepend wrote: post #107
aquilaFiera wrote: post #78

We get to use Markdoc every day and it is a joy to work with. Shameless plug: we're looking for someone to come in and a product manager over the Stripe Docs. Imagine working on docs at the company known for docs. Very fun problems. https://stripe.com/jobs/listing/product-manager-docs/3928998

Thanks for posting this. What is a good way for learning about the salary and compensation for this position? Nothing specific, b it just ballpark to determine if there’s basic compatibility before applying. The title is too specific to get good numbers from googling and I worry that docs product managers wouldn’t make what typical product managers make. [0] [0] https://www.glassdoor.com/Salary/Stripe-Product-Manager…

It's a normal PM position and you'd be in the normal PM salary bands. You'd be my peer. I manage the server-side SDKs, the CLI, the VS Code extension, the React Native SDK, the API upgrade experience, etc. We'd be in the same ladder. (AFAIK there's just one PM ladder at Stripe)

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

#117

Post by docmechanic »

maxerickson wrote: post #104
docmechanic wrote: post #66

Earlier quoted context omitted.

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
"

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

#119

Post by __mharrison__ »

blutack wrote: post #23

Does anyone know of tooling like this but not for only making websites? I have an asciidoc based chain that mostly works for generating both PDF manuals and standalone html docs but it's a bit of a faff to install and set up especially for non-technical users. My dream is something like pandoc but with one or more diagram libraries integrated, native PDF output and all wrapped up in a single binary, maybe with a nice…

Last week I ported my static physical book building tooling from rst-based [0] to markdown (pandoc filter) based.

I've used my rst tooling to publish many books (like Effective Pandas) and am wanting to drop rst in an effort to simplify my life. My pandoc toolchain is not in github yet, but preliminary exploration validates that I can publish my next physical book with it (with things like front matter, indices, etc).

In the process I messed around with MyST and mistletoe. I dropped MyST because it was evident I would need to mess around with Sphinx again. Been there done that. Too much abstraction.

Mistletoe would have worked too (I need to create custom fences/markup for a few features) but I wanted to see if I could do it with Pandoc.

The Pandoc distinction between Blocks and Inlines is annoying as is the requirement to handle everything at once. With Pandoc, you only get notified at the start of an element, not the end which probably complicates it a bit more than Mistletoe would have.

(I still need to port my slide generation tooling and will probably use mistletoe for that. For epub generation I think I will stick with Pandoc.)

0 - https://github.com/mattharrison/rst2nitrile

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

#120

Post by __mharrison__ »

jtbayly wrote: post #60
blutack wrote: post #23

Does anyone know of tooling like this but not for only making websites? I have an asciidoc based chain that mostly works for generating both PDF manuals and standalone html docs but it's a bit of a faff to install and set up especially for non-technical users. My dream is something like pandoc but with one or more diagram libraries integrated, native PDF output and all wrapped up in a single binary, maybe with a nice…

Have you checked out Quarto? https://quarto.org "Quarto® is an open-source scientific and technical publishing system built on Pandoc - Create dynamic content with Python, R, Julia, and Observable. - Author documents as plain text markdown or Jupyter notebooks. - Publish high-quality articles, reports, presentations, websites, blogs, and books in HTML, PDF, MS Word, ePub, and more. - Author with scientific markdown,…

A few folks recommended Quarto to me when I asked about current recommendations recently. My main goal is physical books and that doesn't seem to be a first class citizen anywhere. Looking through Quarto, I can't find reference to markdown syntax for index entries (which indicates that they don't support it.)

Also, I'm heavily biased, but based on my experience I will need to hack whatever tool and I'm not really interested in hacking JS/TS. (My whole reason for getting rid of my rst based tooling is to simplify and sticking in Python simplifies my life, coding in JS/TS not so much.)

Post reply on HN