ApostropheCMS integration 🙏 #5969
Conversation
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
1 Ignored Deployment
|
|
Hello! Thank you for opening your first PR to Astro’s Docs! 🎉 Here’s what will happen next:
|
sarah11918
added
the
add new content
|
Thank you for this contribution, @boutell ! I hope we will get this guide helping people use Apostrophe with Astro before the new year! 🚀 It would help, though, if you first reviewed the style and structure of our other CMS guides. While there is some variation, most guides at least start with a standard set of headings to set the reader up for success, including headings and clear, direct guidance regarding Prerequisites, Adding credentials etc. You will see that our structure generally follows actions the reader will have to complete, in order, and not nouns like "the starter project". Please do review our writing and style guide, as right now much of this doesn't match our existing documentation. You will find our style, including verb tense, how to address the reader and how to focus on clear, direct instructions documented here: https://contribute.docs.astro.build/guides/writing-style/#writing-style This is important for several reasons including having documentation that is straightforward to translate. If you're ever in doubt, consider someone needing to translate this and ask yourself whether phrases, or even entire sentences are necessary to guide someone through installing and using your project. (e.g. "Hang on, don't go there yet! We'll get there!" kind of meta-commentary is extra content to translate, extra content to read, and is even sometimes is a sign that maybe steps should in fact be put in a different order so that the instructions follow a logical linear pattern.) Since you are the expert in how to set up and use Apostrophe with Astro, not me, it's helpful if you could take a pass at trying to match our existing guides first before I do my editing pass (where I might lose some important information or nuance, or have questions as I'm rewriting to match our existing style and structure). I think this will be easier on both of us to have you do a pass first, where you can be sure you're giving the most important information in our more direct, structured style. Then, I can just check for some final polish! Thank you, and I look forward to having another CMS guide for Astro users in our docs! |
|
Got it! Thanks for getting back to me so quickly! I will take another pass.
THOMAS BOUTELL | CHIEF TECHNOLOGY OFFICER
APOSTROPHECMS | apostrophecms.com | he/him/his
…On Wed, Dec 27, 2023 at 1:59 PM Sarah Rainsberger ***@***.***> wrote:
Thank you for this contribution, @boutell <https://github.com/boutell> !
I hope we will get this guide helping people use Apostrophe with Astro
before the new year! 🚀
It would help, though, if you first reviewed the style and structure of
our other CMS guides. While there is some variation, most guides at least
start with a standard set of headings to set the reader up for success,
including headings and clear, direct guidance regarding Prerequisites,
Adding credentials etc. You will see that our structure generally follows
*actions* the reader will have to complete, in order, and not nouns like
"the starter project".
Please do review our writing and style guide, as right now much of this
doesn't match our existing documentation. You will find our style,
including verb tense, how to address the reader and how to focus on clear,
direct instructions documented here:
https://contribute.docs.astro.build/guides/writing-style/#writing-style
This is important for several reasons including having documentation that
is straightforward to translate. If you're ever in doubt, consider someone
needing to translate this and ask yourself whether phrases, or even entire
sentences are necessary to guide someone through installing and using your
project. (e.g. "Hang on, don't go there yet! We'll get there!" kind of
meta-commentary is extra content to translate, extra content to read, and
is even sometimes is a sign that maybe steps should in fact be put in a
different order so that the instructions follow a logical linear pattern.)
Since you are the expert in how to set up and use Apostrophe with Astro,
not me, it's helpful if you could take a pass at trying to match our
existing guides first before I do my editing pass (where I might lose some
important information or nuance, or have questions as I'm rewriting to
match our existing style and structure). I think this will be easier on
both of us to have you do a pass first, where you can be sure you're giving
the most important information in our more direct, structured style. Then,
I can just check for some final polish!
Thank you, and I look forward to having another CMS guide for Astro users
in our docs!
—
Reply to this email directly, view it on GitHub
<#5969 (comment)>, or
unsubscribe
<https://github.com/notifications/unsubscribe-auth/AAAH27NAIQE5CAW2HSC2AMDYLRV2FAVCNFSM6AAAAABBETKAJOVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTQNZQGU2TIMJZHE>
.
You are receiving this because you were mentioned.Message ID:
***@***.***>
|
|
Hi @boutell ! Just wondering whether you still wanted to take another pass at this, or, now that we're back after the holidays running at full speed, would you like Team Docs to do some work on this with our suggestions to help get this moving? |
|
Hi Sarah, thanks for the nudge! I admit my motivation I got buried in
Christmas cookies but I'm back in the saddle.
One thing I'm wondering about is whether we should essentially be pointing
to this documentation with a short page in your style:
https://apostrophecms.com/extensions/astro-integration
Or, rewriting that guide in your style for inclusion on the Astro site —
which would be great but I'm not sure which is best from your perspective.
Thanks!
…On Mon, Jan 8, 2024 at 10:27 AM Sarah Rainsberger ***@***.***> wrote:
Hi @boutell <https://github.com/boutell> ! Just wondering whether you
still wanted to take another pass at this, or, now that we're back after
the holidays running at full speed, would you like Team Docs to do some
work on this with our suggestions to help get this moving?
—
Reply to this email directly, view it on GitHub
<#5969 (comment)>, or
unsubscribe
<https://github.com/notifications/unsubscribe-auth/AAAH27PI4PLL7BHCQ2XISRLYNQF5JAVCNFSM6AAAAABBETKAJOVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTQOBRGIZDOMRVGI>
.
You are receiving this because you were mentioned.Message ID:
***@***.***>
--
THOMAS BOUTELL | CHIEF TECHNOLOGY OFFICER
APOSTROPHECMS | apostrophecms.com | he/him/his
|
|
Hey Tim! No one says we can't do both! 😄 You can immediately make a tiny "stub" page, with not much content at all and include a link to the Apostrophe documentation. This gets the page in there right away, and allows people to find it, and the guide already written. Then, later, the page can be updated in a subsequent PR more leisurely, and we can decide if it makes sense to have content here (which I'm happy to have!) and we can discuss what that could/should look like based on what exists elsewhere. Here are some very minimal examples you could use as a model that would be very easy to merge in quickly:
You'll see the bar can be quite low! 😄 Let me know what you think! |
|
Hmm, I thought I'd done the stub one (: I will take another look at that
PR! I was working on a longer one but this is a real crunch month.
…On Mon, Jan 8, 2024 at 10:49 AM Sarah Rainsberger ***@***.***> wrote:
Hey Tim! No one says we can't do both! 😄
You can immediately make a tiny "stub" page, with not much content at all
and include a link to the Apostrophe documentation. This gets the page in
there right away, and allows people to find it, and the guide already
written.
Then, later, the page can be updated in a subsequent PR more leisurely,
and we can decide if it makes sense to have content here (which I'm happy
to have!) and we can discuss what that could/should look like based on what
exists elsewhere.
Here are some very minimal examples you could use as a model that would be
very easy to merge in quickly:
- https://docs.astro.build/en/guides/cms/spinal/
- https://docs.astro.build/en/guides/cms/sanity/
- https://docs.astro.build/en/guides/cms/prismic/
You'll see the bar can be quite low! 😄 Let me know what you think!
—
Reply to this email directly, view it on GitHub
<#5969 (comment)>, or
unsubscribe
<https://github.com/notifications/unsubscribe-auth/AAAH27PSRUMCWVKNX3RJWW3YNQIP3AVCNFSM6AAAAABBETKAJOVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTQOBRGMYDKNBWGM>
.
You are receiving this because you were mentioned.Message ID:
***@***.***>
--
THOMAS BOUTELL | CHIEF TECHNOLOGY OFFICER
APOSTROPHECMS | apostrophecms.com | he/him/his
|
|
OK yes I see the difference. Creating a proper stub.
…On Tue, Jan 16, 2024 at 12:02 PM Tom Boutell ***@***.***> wrote:
Hmm, I thought I'd done the stub one (: I will take another look at that
PR! I was working on a longer one but this is a real crunch month.
On Mon, Jan 8, 2024 at 10:49 AM Sarah Rainsberger <
***@***.***> wrote:
> Hey Tim! No one says we can't do both! 😄
>
> You can immediately make a tiny "stub" page, with not much content at all
> and include a link to the Apostrophe documentation. This gets the page in
> there right away, and allows people to find it, and the guide already
> written.
>
> Then, later, the page can be updated in a subsequent PR more leisurely,
> and we can decide if it makes sense to have content here (which I'm happy
> to have!) and we can discuss what that could/should look like based on what
> exists elsewhere.
>
> Here are some very minimal examples you could use as a model that would
> be very easy to merge in quickly:
>
> - https://docs.astro.build/en/guides/cms/spinal/
> - https://docs.astro.build/en/guides/cms/sanity/
> - https://docs.astro.build/en/guides/cms/prismic/
>
> You'll see the bar can be quite low! 😄 Let me know what you think!
>
> —
> Reply to this email directly, view it on GitHub
> <#5969 (comment)>,
> or unsubscribe
> <https://github.com/notifications/unsubscribe-auth/AAAH27PSRUMCWVKNX3RJWW3YNQIP3AVCNFSM6AAAAABBETKAJOVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTQOBRGMYDKNBWGM>
> .
> You are receiving this because you were mentioned.Message ID:
> ***@***.***>
>
--
THOMAS BOUTELL | CHIEF TECHNOLOGY OFFICER
APOSTROPHECMS | apostrophecms.com | he/him/his
--
THOMAS BOUTELL | CHIEF TECHNOLOGY OFFICER
APOSTROPHECMS | apostrophecms.com | he/him/his
|
|
I have updated this PR to be a properly stubby stub, please review 🙏 Thank you! |
sarah11918
added
the
Merge Queue
There was a problem hiding this comment.
Looking good @boutell ! Thanks so much for this, and you're welcome to improve this page over time, as you like!
Welcome to Team Docs! 🥳
|
So you've approved it, but your localization team has next crack, and of course as a non-owner I don't do the merging... so I'll be standing by, making 🍿 🙏 |
|
Hahah, yup, the "merge queue" label makes it fair game for merging for whoever is next around/available to merge... which would be... me! now! pop that popcorn... |
|
🍿🍿🍿💯 Thank you.
…On Wed, Jan 17, 2024 at 9:04 AM Sarah Rainsberger ***@***.***> wrote:
Merged #5969 <#5969> into main.
—
Reply to this email directly, view it on GitHub
<#5969 (comment)>, or
unsubscribe
<https://github.com/notifications/unsubscribe-auth/AAAH27KLD336XQVSTJPPCQ3YO7K5TAVCNFSM6AAAAABBETKAJOVHI2DSMVQWIX3LMV45UABCJFZXG5LFIV3GK3TUJZXXI2LGNFRWC5DJN5XDWMJRGUYTCOBVGI4TANI>
.
You are receiving this because you were mentioned.Message ID:
***@***.***>
--
THOMAS BOUTELL | CHIEF TECHNOLOGY OFFICER
APOSTROPHECMS | apostrophecms.com | he/him/his
|
Co-authored-by: Sarah Rainsberger <[email protected]>
Description (required)
Add ApostropheCMS to the CMS guide.
Compatibility
Tested compatible with both Astro 3.x and Astro 4.x, but of course our starter projects and documentation are using 4.x.
Thank you!