Skip to content

Conversation

lbv-stripe
Copy link
Contributor

@lbv-stripe lbv-stripe commented Oct 27, 2022

This PR:

  • Fixes a few confusion points in the IA (rendering and validation aren't part of syntax, common examples aren't an integration guide, config objects deserve their own section).
  • Makes sure that the Node, Tag, etc articles are complete. Moves information that only existed in Syntax into those articles.
  • Adds information about annotations to the Attributes page, since that's basically what annotations do.
  • Moves built-in features to the tops of their pages — e.g. built-in tags are now higher than info about custom tags. (This makes it less painful to move some of that info out of Syntax.)
  • Does a bit of rewriting and adds a few examples to support all this.

This solves most of the problems in https://jira.corp.stripe.com/browse/COSTRAT-76, plus some extra cleanup.

@vercel
Copy link

vercel bot commented Oct 27, 2022

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name Status Preview Updated
markdoc ✅ Ready (Inspect) Visit Preview Oct 27, 2022 at 4:14PM (UTC)
markdoc-simple-nextjs ✅ Ready (Inspect) Visit Preview Oct 27, 2022 at 4:14PM (UTC)

Copy link
Contributor

@mfix-stripe mfix-stripe left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Chatted w/ @lbv-stripe offline. We are going to split this up into smaller changes 🙂

},
{
title: 'Core concepts',
title: 'Core features',
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I strongly think we should keep /docs/render in the first section. With that, I think "Core concepts" is a better fit, but I could be convinced about "Core features".

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Either way, for changing concepts like this, I think we need some outside data (even if it's a collection of anecdata), before changing IA stuff.

A lot of this comes down to personal opinion and personal learning styles, so we want to be more objective.

@mfix-stripe mfix-stripe changed the title Update IA and summary [WIP] Update IA and summary Oct 31, 2022
@lbv-stripe
Copy link
Contributor Author

Going to break this into smaller PRs

@lbv-stripe lbv-stripe closed this Oct 31, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants