Closed sarah11918 closed 1 year ago
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.
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?
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
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? :)
@CBID2 you quoted @Hopelezz but tagged me 😆
@CBID2 you quoted @Hopelezz but tagged me 😆
Ooh sorry lol. My offer still remains though :)
I'd be fine working on it with you if you want. It shouldn't be too much to do.
@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
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:
@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 :)
@sarah11918 , would you mind providing us with a list of file names to be relabeled and we can collaborate on names?
Hopelezz#1878 Just sent you a friend request on Discord! I'm Chrissy(she/her)!
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!
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.
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
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...'
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.
I was thinking something more along the lines of:
Inside CONTRIBUTING.md we would give a brief shoutout to each file and what they do:
@CBID2 Sorry I was able to be on last evening. I'm swamped trying to buy a house 😅
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?
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
I opted against it in my head because the whole guide is calling them recipes. Unless we change every reference from
Recipies
toHow-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?
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
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.
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!
/contribution-guides/
Contributor sounds odd.
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.
/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! :)
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:
src
or anything) called /contributor-guides/
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??
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! :)
@sarah11918
My PR: #3392
Reopening this, since the issue isn't done, and @Hopelezz is up next to finish it! :raised_hands:
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...):
contributor-guides
that point to other guidesOnly 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!
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.
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.
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
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?
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...):
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
Having a conversation in the
#docs
channel in Discord. We're proposing:RECIPES.md
is a writing guide? :sweat_smile: