Tip 24 - mise en place

Jul 17, 2024

Astro Docs contains several guides to working with third-party services such as CMS guides, deploy hosts, and backend services. And, there are several different “starting points” for the journey of integrating another service with Astro. Do you already have an existing third-party… account? project? token? Do you even have an Astro project yet?

The French cooking term “mise en place” refers to laying out your ingredients ahead of time so that you aren’t trying to find or prepare ingredients while you are trying to follow the recipe. “How to build a blog with Astro and CMS X” can feel like baking a pie with a crust, filling, and topping as you open one project here while configuring frontmatter fields over there and adding an environment variable to a deploy host over yonder.

One PR suggestion I often make for these guides is to assume people can find and follow existing documentation for side quests, and put anything that’s not about integrating the two existing services as a stated prerequisite. We have documentation on running create astro. This guide does not need to cover it. Similarly, a CMS itself should be documenting how to configure their own settings and use their own dashboard.

✅ Prerequisites: An Astro project configured for hybrid rendering and an existing CMS X project with title, author, date, and body field labels created. You will also need your personal token from the CMS dashboard for your deploy host.
😐 Run create astro… Sign up for a free account with “CMS X.” …

Your marketing concerns itself with your project’s “unique selling proposition” (USP). The best recipes and guides also focus on exactly what they can bring to the table that no one else can, or specifically, what no one else has written. (In the Astro + X guides case, it’s connecting two existing services.)

Identify the parts of your guide that are already documented, and don’t redocument them. Make them a prerequisite to even starting! It’s not being “lazy” or “incomplete.” It is keeping your readers focused on your task so that they aren’t trying to bake fudge in the middle of making the ice cream it will go into.

Not only will you save time writing, you’ll reduce your maintenance burden when something (inevitably) changes in a part of the process that you might not even be responsible for. When a CMS changes their settings menu from Settings > Project > Token to Settings > Tokens, you can remain blissfully unaware with your still-functioning guide!

See the whole list of tips!

Toggle Comments