DEV Community

Cover image for Markdoc: 10 Minute Docs Audit
DocumentWrite
DocumentWrite

Posted on

Markdoc: 10 Minute Docs Audit

Markdoc is a content authoring tool, creating by Stripe. Markdoc is open-source and natively integrates with Next.js and React.

I run a technical documentation business specializing in writing and editing documentation. I made this series to share my insights and help projects craft impactful documentation.

What's The Criteria?
3- Excellent
2 - OK
1 - Poor

Purposeful: Does the QuickStart explain what problem it's trying to solve? Who is the intended audience?

UX Experience: How seamless is the experience? Must the user create an account to get through the Quickstart? Does the Quickstart elicit a sense of joy and achievement?

Accurate: Are the instructions correct? Are they complete?

The Results

Not going to lie. I was expecting great things from Markdoc and came away from this review disappointed. The landing page implies that Markdoc is for everyone, but it doesn't take long for the docs to get into the weeds of JavaScript transpilers and setext headings. 🀯

I just wanted to get a CMS running by lunchtime so I can spend the rest of the week focusing on content. I don't have the brain power to ponder the the pros and cons of Markdoc's tag system vs MDX.

I'm sure Markdoc is a lovely tool, but it's strictly for the nerds. Looks like I won't be giving up Docusaurus anytime soon.

Score
Purposeful 1
UX Experience 1.5
Accurate 2

Are you interested in a FREE Quickstart audit for your company? Start here.

Top comments (0)

11 Tips That Make You a Better Typescript Programmer

typescript

1 Think in {Set}

Type is an everyday concept to programmers, but it’s surprisingly difficult to define it succinctly. I find it helpful to use Set as a conceptual model instead.

#2 Understand declared type and narrowed type

One extremely powerful typescript feature is automatic type narrowing based on control flow. This means a variable has two types associated with it at any specific point of code location: a declaration type and a narrowed type.

#3 Use discriminated union instead of optional fields

...

Read the whole post now!

πŸ‘‹ Kindness is contagious

Please leave a ❀️ or a friendly comment on this post if you found it helpful!

Okay