Better discoverability of contributing guides

[sarah11918]

Having a conversation in the #docs channel in Discord. We're proposing:

• creating a Contributing directory for all our various kinds of contributing guides
• renaming and moving ALL BUT CONTRIBUTING.md (since that's an expected file people look for)
  • this way, files don't need to follow the ALLCAPS.md file format and can actually be more descriptive
  • e.g. Do people know that RECIPES.md is a writing guide? :sweat_smile:
• updating the docs contributing page with the new links, now that locations and filenames have changed
• linking all these other contributing guides in the new directory prominently in CONTRIBUTING.md for discoverability from there.

[sarah11918]

I think we are willing to experiment with this change! BUT...

DO NOT make a PR yet, because I we are talking about renaming/moving files, and it will be easier to agree to that here first.

So, propose filenames for the ALLCAPS.md contributing guides in this thread first.

[Jothsa]

Personally, I find the all caps style pretty hard to read. I think for readability of long file names it's best if the words are separated by a symbols.

I think that since they will be in the contributing directory, suffixing each file with "guide" might be enough. (Recipes-Guide.md, Writing-Guide.md) To be more explicit they could be suffixed with "contributing guide" (Writing-Contributing-Guide.md, Recipes-Contributing-Guide.md). It is verbose, but I prefer this way because it is the most explicit. Thought?

[Hopelezz]

I've honestly looked at RECIPES in the codebase and went... What is that?

Names are super important when trying to provide clarity. Clever names work, but can be misleading or confusing to the uninitiated.

WRITING GUIDE might actually be a better name. If it's a writing guide for a specific subject then: WRITING GUIDE- DOCS

[CBID2]

I've honestly looked at RECIPES in the codebase and went... What is that?

Names are super important when trying to provide clarity. Clever names work, but can be misleading or confusing to the uninitiated.

WRITING GUIDE might actually be a better name. If it's a writing guide for a specific subject then: WRITING GUIDE- DOCS

Same here @Hopelezz! I’m new to Astro so when I saw “recipes” and thought “so are we cooking or??” Do you want to work on this together once @sarah11918 gives the thumbs up? :)

[Jothsa]

@CBID2 you quoted @Hopelezz but tagged me 😆

[CBID2]

@CBID2 you quoted @Hopelezz but tagged me 😆

Ooh sorry lol. My offer still remains though :)

[Jothsa]

I'd be fine working on it with you if you want. It shouldn't be too much to do.

[Hopelezz]

@Jothsa and @CBID2 , I'm down for team effort 🔥. If either of you want to we can tackle it this weekend?

Free Saturday @5pm CST and possibly Sunday.

Discord name is Hopelezz#1878

[sarah11918]

I would say our naming was less clever and more, "If the convention is ALLCAPS then we need a single word or this will be very difficult to read." :sweat_smile:

OK, so what I want to see in this thread is a proposal for all the new file names here. We no longer need caps, and yes, we'll want - separators between words.

Once we agree on the file names, then I think a PR can go forward! :raised_hands:

[CBID2]

@Jothsa and @CBID2 , I'm down for team effort 🔥. If either of you want to we can tackle it this weekend?

Free Saturday @5pm CST and possibly Sunday.

Discord name is Hopelezz#1878

That's 6:23pm EDT for me, so that's fine :)

[Hopelezz]

@sarah11918 , would you mind providing us with a list of file names to be relabeled and we can collaborate on names?

[CBID2]

Hopelezz#1878 Just sent you a friend request on Discord! I'm Chrissy(she/her)!

[sarah11918]

It should be all the ALLCAPS Markdown files at the root of the project EXCEPT for CONTRIBUTING.md. That one should stay as is. anything that looks like a guide (for topic, or by role of contributor) of any kind that I would have written! And, they're probably all linked to in docs from the new contributing page. I'm not looking at the repo right now, but I think that should give you enough to go on!

[Jothsa]

Should the first letter of each word be capitalized? Personally, I prefer that style, but all lowercase is fine. I have a conflict Saturday evening, but if you two can go ahead without me. If you'd like, I can help out Sunday. I'm Jothsa#8724 on Discord.

[tsxoxo]

I didn't discover the writing guides for weeks while writing a guide for the docs :).

I didn't even think to check the Astro docs for that. I'm very happy I asked on Discord and found @sarah11918 who pointed me to the docs contributing page, because that's some good stuff there.

Cool to see this improvement happening!

---

In my specific case I would have probably found the guides sooner if they had been prominently featured in CONTRIBUTING.md or mb README.md. I especially combed through CONTRIBUTING.md a few times to find specific writing guidelines or links to such documents.

For me this would have already made a difference - a section in CONTRIBUTING.md with a heading like Writing Guidelines and a link to the existing page in the docs.

The question of naming is kind of secondary for me, but might point to a larger issue - people being confronted with 3 lengthy files could be a lot (CONTRIBUTING.md + WRITING GUIDE.md + RECIPES.md). It didn't break me but it got a little messy 😵‍💫.

In my case - expanding on an existing stub in the CMS recipes section, being sort of familiar with PRs - a few paragraphs of the WRITING GUIDE.md were really the thing that I needed: 'write informally but not too casually', 'say you not we', 'don't add narratives'.

Reading RECIPES.md was fascinating tho, I learned what recipes are 😅.

I'm not sure if this is even such a problem. But maybe it kind of points back at the issue of discoverability of relevant information. Just another facet.

---

More ideas

1. Put the existing guides in a folder called Writing guides. Link to it in CONTRIBUTING.md. Introduce the links with a guiding explanation - e.g. 'WRITING GUIDE.MD is to learn about the tone we use, and to learn how we structure our guides. RECIPES.md is for people contributing to the following sections of the docs: recipes, CMS, xyz...'

2. Make one giga file for all things about writing. I know You've probably thought this one through and rejected it already for good reasons, so I'm simply adding this for completeness :). It would be necessary to give it a table of contents at the top and a clear, welcoming intro. This set up might have the advantage that the guiding explanation (see idea 1) would be closer to the content.

[Hopelezz]

I was thinking something more along the lines of:

• Guide - Maintainer.md
• Guide - Translating.md
• Guide - Writing.md
• Guide - Recipies (How-Tos).md

Inside CONTRIBUTING.md we would give a brief shoutout to each file and what they do:

• Guide - Maintainer: A how-to guide on maintaining the project
• Guide - Translating: A guide on translating project content
• Guide - Writing: A guide on writing for the project
• Guide - Recipes (How-Tos): Step-by-step how-to guides for accomplishing specific tasks

@CBID2 Sorry I was able to be on last evening. I'm swamped trying to buy a house 😅

[CBID2]

I was thinking something more along the lines of:

• Guide - Maintainer.md

• Guide - Translating.md

• Guide - Writing.md

• Guide - Recipies (How-Tos).md

Inside CONTRIBUTING.md we would give a brief shoutout to each file and what they do:

• Guide - Maintainer: A how-to guide on maintaining the project

• Guide - Translating: A guide on translating project content

• Guide - Writing: A guide on writing for the project

• Guide - Recipes (How-Tos): Step-by-step how-to guides for accomplishing specific tasks

@CBID2 Sorry I was able to be on last evening. I'm swamped trying to buy a house 😅

Hmm.. How about we turn recipes into How-tos instead?

[Hopelezz]

I opted against it in my head because the whole guide is calling them recipes. Unless we change every reference from Recipies to How-To

[CBID2]

I opted against it in my head because the whole guide is calling them recipes. Unless we change every reference from Recipies to How-To

Ohh I see @Hopelezz. I mean How-To is a much more common term for the purpose of these guides and it'll help contributors who are new to Astro and tech in general to comprehend them. Does that make sense?

[kamoshi]

In the context of programming the so called "cookbooks" are books which contain short code snippets - "recipes" that help you solve some very specific and self contained problem.

I'm not sure if there's a better name for this type of content other than recipes. The term "how to" feels more general (hyperonymous) to me personally

[CBID2]

Hey everyone. Here’s a spreadsheet that I created to address this issue: https://docs.google.com/spreadsheets/d/1-SFhgI-mSVB9mkDyYfnNXw7DvIVqt6_WR0e4waD-3G0/edit

@sarah11918, you made a good point on How-tos and SupportSquad being unclear. Perhaps we can them Explainers or Explainer Guides. They seem straightforward.

[sarah11918]

OK, just so these are all copied here and people don't have to go to another page to view the spreadsheet, I'm copying the data here:

Curent Name	Proposed Name
README.md	README.md
SUPPORT.md	SUPPORT.md
WRITING.md	Guide-WRITING.md
RECIPES.md	Guide-HOW-TOS.md
MAINTAINERS.md	Guide-MAINTAINERS.md
TRANSLATING.md	Guide-TRANSLATING.md

So, let's go one-by-one:

README has to stay as README! That's what people expect. This should link to the Contributing guide (ooh, I don't see that one above. I'll do that one next)

CONTRIBUTING.md Also has to stay the same! That's what people expect. I think it's also OK for this one to stay at the root of the project, since it's such a common file to have. So, no changes to the filenames of either of these.

If we are going to make a new folder e.g. /contributor-guides/ then I don't think all the files need to start with "guide." If someone navigates into that folder, I think that would be distracting to see as the start of all the file names, and would make them need to work harder to see which guides they actually are.

So, what do we think about renaming and moving to /contributor-guides/:

Curent Name	Proposed Name
SUPPORT.md	support-squad-guide-to-docs.md
WRITING.md	writing-and-style-guide.md
RECIPES.md	submitting-a-recipe.md
MAINTAINERS.md	astro-maintainers-guide-to-docs.md
TRANSLATING.md	translating-astro-docs.md

I think these all make it clear that sometimes it's about a role needing to have their own generic "guide" to the docs (all the ways that, in your role, you might have special responsibilities) and otherwise, the title based on an action like submitting a recipe or translating the docs.

By giving a longer "writing and style guide", I think we catch both people who are execting to find a writing guide, and people who are expecting to find a style guide!

[Hopelezz]

/contribution-guides/ Contributor sounds odd.

Curent Name | My Proposed Name -- | -- SUPPORT.md | support-squad-guide-to-docs.md WRITING.md | writing-and-style-guide-to-docs.md RECIPES.md | submitting-a-recipe-guide-to-docs.md MAINTAINERS.md | maintainers-guide-to-docs.md TRANSLATING.md | translating-guide-to-docs.md

It's understood we're in Astro. So I think we can remove it from the names. The Context in front makes it cleaner I feel.

[CBID2]

/contribution-guides/ Contributor sounds odd.

Curent Name My Proposed Name SUPPORT.md support-squad-guide-to-docs.md WRITING.md writing-and-style-guide-to-docs.md RECIPES.md submitting-a-recipe-guide-to-docs.md MAINTAINERS.md maintainers-guide-to-docs.md TRANSLATING.md translating-guide-to-docs.md It's understood we're in Astro. So I think we can remove it from the names. The Context in front makes it cleaner I feel.

I love the new names @sarah11918. As far as the potential issue with the new Writing guide title, I think naming it Style Guide could help since writing is a “style”. Also, I’d love to be the person to make this pull request! :)

[sarah11918]

OK, I'm going to make some executive decisions here and give y'all some PR tasks to do!! :partying_face:

My decisions:

• the folder really should be /contributor-guides/ and not "contribution" because these folders are FOR the contributors. Not every guide is specifically about "making a contribution" or "how to make a contribution". There are some guides that are for particular roles, like maintainers and support squad. So, the folder should refer to the people, not the contribution itself.

• I like writing-and-style-guide.md BECAUSE it is too long! I think it will stand out and people will notice it! Some people expect to see a writing guide, and some expect to see a style guide, so this makes sure everyone knows they have the right file!

• I do want the maintainers file to be labelled astro-maintainers-guide-to-docs because unlike many projects, our docs are an entirely separate repo, and sometimes people think of themselves as an "astro maintainer" but not necessarily a maintainer when it comes to this docs repo. This document is to be a bit of a reminder and nudge for them specifically for that reason, to remind them that as an Astro maintainer, you have a special role here in this docs repo. I agree in general with not using Astro when it's assumed, and that's why I chose not to use it for the support squad document.

We're going to do this in stages so that nothing breaks :laughing:

@CBID2 I'd love for you to submit a PR that:

• creates a new folder at the root of the project (not in src or anything) called /contributor-guides/
• makes an EXACT COPY of the content of the existing files I listed above and puts them in this new folder, with the new names I suggested in my earlier post. (Do not delete the existing files, because other places link to them.)

This means that when we're done, we will have two versions of all those guides, one with the old name at the root and one with the new name in the new folder. That's fine. We'll handle searching for and updating any links to point to these new files in a subsequent PR. So, these new files will just sit there, waiting to be linked to in the next PR, which we can put @Hopelezz on once this is done!

Are you up for that, Chrissy??

[CBID2]

OK, I'm going to make some executive decisions here and give y'all some PR tasks to do!! 🥳

My decisions:

• the folder really should be /contributor-guides/ and not "contribution" because these folders are FOR the contributors. Not every guide is specifically about "making a contribution" or "how to make a contribution". There are some guides that are for particular roles, like maintainers and support squad. So, the folder should refer to the people, not the contribution itself.
• I like writing-and-style-guide.md BECAUSE it is too long! I think it will stand out and people will notice it! Some people expect to see a writing guide, and some expect to see a style guide, so this makes sure everyone knows they have the right file!
• I do want the maintainers file to be labelled astro-maintainers-guide-to-docs because unlike many projects, our docs are an entirely separate repo, and sometimes people think of themselves as an "astro maintainer" but not necessarily a maintainer when it comes to this docs repo. This document is to be a bit of a reminder and nudge for them specifically for that reason, to remind them that as an Astro maintainer, you have a special role here in this docs repo. I agree in general with not using Astro when it's assumed, and that's why I chose not to use it for the support squad document.

We're going to do this in stages so that nothing breaks 😆

@CBID2 I'd love for you to submit a PR that:

• creates a new folder at the root of the project (not in src or anything) called /contributor-guides/
• makes an EXACT COPY of the content of the existing files I listed above and puts them in this new folder, with the new names I suggested in my earlier post. (Do not delete the existing files, because other places link to them.)

This means that when we're done, we will have two versions of all those guides, one with the old name at the root and one with the new name in the new folder. That's fine. We'll handle searching for and updating any links to point to these new files in a subsequent PR. So, these new files will just sit there, waiting to be linked to in the next PR, which we can put @Hopelezz on once this is done!

Are you up for that, Chrissy??

Yes I am @sarah11918! :)

[CBID2]

@sarah11918

My PR: #3392

[sarah11918]

Reopening this, since the issue isn't done, and @Hopelezz is up next to finish it! :raised_hands:

[sarah11918]

Now, @Hopelezz , when you're ready, you get to....

Do a search on the entire docs repo for SUPPORT.md / WRITING.md / RECIPES.md / MAINTAINERS.md / TRANSLATING.md and update any links that still point there. This should include (but might not be limited to...):

• Update the links on our Contribute to Docs page in docs https://docs.astro.build/en/contribute/ so they point to the new files with the better names
• Update the "Translate this page" link in the RightSidebar which currently links to the translator guide. It should now point to the new one
• Update all the new guides in contributor-guides that point to other guides
• Update the existing README.md and CONTRIBUTING.md that should NOT have changed/moved, but still probably link to other guides.

Only when you're sure you've caught and updated EVERYTHING, we can delete from the root: SUPPORT.md WRITING.md RECIPES.md MAINTAINERS.md TRANSLATING.md

Remember, please do NOT move/delete README.md nor CONTRIBUTING.md. Those should both stay in the root, with their existing titles! Only their content should be updated so that they now link to the newly-named/located guide!

[CBID2]

Now, @Hopelezz , when you're ready, you get to....

Do a search on the entire docs repo for SUPPORT.md / WRITING.md / RECIPES.md / MAINTAINERS.md / TRANSLATING.md and update any links that still point there. This should include (but might not be limited to...):

• Update the links on our Contribute to Docs page in docs https://docs.astro.build/en/contribute/ so they point to the new files with the better names
• Update the "Translate this page" link in the RightSidebar which currently links to the translator guide. It should now point to the new one
• Update all the new guides in contributor-guides that point to other guides
• Update the existing README.md and CONTRIBUTING.md that should NOT have changed/moved, but still probably link to other guides.

Only when you're sure you've caught and updated EVERYTHING, we can delete from the root: SUPPORT.md WRITING.md RECIPES.md MAINTAINERS.md TRANSLATING.md

Remember, please do NOT move/delete README.md nor CONTRIBUTING.md. Those should both stay in the root, with their existing titles! Only their content should be updated so that they now link to the newly-named/located guide!

Hey @sarah11918. It’s been a while since you reopened this issue. If Hopeless still does not respond, I’d be happy to do the other PR for this issue, so it won’t go stale.

[sarah11918]

Hi @CBID2, we haven't heard from @Hopelezz , so I guess Mark is still busy. Don't worry Mark, we'll get you involved next time!

Sure, go ahead and start this next part of the Issue. Please start by following only the four bullet points above. (Don't do any file deleting when you initially create the PR, because that's harder to recover from. :sweat_smile: ) Let's make sure the rest of the PR tasks are fully working first.

[CBID2]

Hi @CBID2, we haven't heard from @Hopelezz , so I guess Mark is still busy. Don't worry Mark, we'll get you involved next time!

Sure, go ahead and start this next part of the Issue. Please start by following only the four bullet points above. (Don't do any file deleting when you initially create the PR, because that's harder to recover from. :sweat_smile: ) Let's make sure the rest of the PR tasks are fully working first.

Got it @sarah11918

[CBID2]

Hi @CBID2, we haven't heard from @Hopelezz , so I guess Mark is still busy. Don't worry Mark, we'll get you involved next time!

Sure, go ahead and start this next part of the Issue. Please start by following only the four bullet points above. (Don't do any file deleting when you initially create the PR, because that's harder to recover from. :sweat_smile: ) Let's make sure the rest of the PR tasks are fully working first.

Got it @sarah11918

Just to be clear @sarah11918, you mean the first four here?

[sarah11918]

Yes:

Do a search on the entire docs repo for SUPPORT.md / WRITING.md / RECIPES.md / MAINTAINERS.md / TRANSLATING.md and update any links that still point there. This should include (but might not be limited to...):

• Update the links on our Contribute to Docs page in docs docs.astro.build/en/contribute so they point to the new files with the better names
• Update the "Translate this page" link in the RightSidebar which currently links to the translator guide. It should now point to the new one
• Update any links inside the new guides in contributor-guides that point to other guides
• Update any necessary links inside of the existing README.md and CONTRIBUTING.md (again, these files themselves should not be changed/moved, but still probably link to other guides)

[CBID2]

Yes:

Do a search on the entire docs repo for SUPPORT.md / WRITING.md / RECIPES.md / MAINTAINERS.md / TRANSLATING.md and update any links that still point there. This should include (but might not be limited to...):

• Update the links on our Contribute to Docs page in docs docs.astro.build/en/contribute so they point to the new files with the better names
• Update the "Translate this page" link in the RightSidebar which currently links to the translator guide. It should now point to the new one
• Update any links inside the new guides in contributor-guides that point to other guides
• Update any necessary links inside of the existing README.md and CONTRIBUTING.md (again, these files themselves should not be changed/moved, but still probably link to other guides)

Done! :) Here is the pull request