Writing guidelines section is living on an island

[OnkarRuikar]

The writing guidelines are not directly reachable from anywhere on the website. Many don't even know that they exit.

Where should links to these go?
a. In the main menu under "Guides" menu:

b. In the "Help improve MDN" section:

---

What are your views on this?
Are these locations ok? Please suggest other locations that you think would be suitable.

[dipikabh]

Hi @OnkarRuikar, glad you brought this up. This is a known problem.

I recently proposed internally to add a "?" help menu button at the bottom right corner on the website. The help menu could serve as the home for glossary, contribution guide, and our writing guidelines.

On click, it might look like this:

[OnkarRuikar]

I recently proposed internally to add a "?" help menu button at the bottom right corner on the website.

Where in the bottom, in footer? Would a tiny character be noticeable enough?
These are pretty big sections, so I think they deserve more exposure.

[estelle]

We should add these links to the site, but I think a (?) in the bottom corner is not intituitive and doesn't provide the visibility these links needs (though, better to add them under a (?) than not at all.).

The CoC link is in the footer as "Community Participation Guidelines". Most in our community will be looking for "CoC", not "CPG", so maybe we can update that to "Community Participation Guidelines (Code of Conduct)", but that seems long.
If we can't change that verbiage, which I don't think we can, we should link a few occurrences of "code of conduct" within the community pages, so someone looking for it will find it.

The MDN tour should be a link from the home page. I assume. I didn't know we had a tour and can't find it.

see my comment below for the other links

[estelle]

mdn/content#32846 adds the glossary to the web tech landing page.
mdn/content#32850 add links to Mozilla's CoC in 5 places where CoC is mentioned.
This does not solve the issues being discussed, but helps address two issues brought up in this discussion

[caugner]

If we can't change that verbiage, which I don't think we can, we should link a few occurrences of "code of conduct" within the community pages, so someone looking for it will find it.

@estelle FWIW The Community guidelines page has a Code of conduct section, so it can be found via full-text search. However, only a single site-search query in the last 12 months contained the word "conduct".

[dipikabh]

The idea behind the "?" menu was to provide an on-demand list of resources, accessible from every page. The motivation was the same - there is no direct way to reach writing and community guidelines, Glossary, and Code of Conduct (COC). The purpose of the "?" menu would be to provide an on-demand link to resources that are not directly related to web technology (excluding glossary), but concern contribution and community participation guidelines. The "?" would remain visible while scrolling, positioned similarly to "scroll to top" or "chat" buttons found on other websites.

We could use a line separator to group logical items. For instance, the tour and glossary could be grouped together, followed by writing and contribution guidelines in another group, and the Code of Conduct (COC) in the last.

@estelle, we currently don't have a tour. My proposal was to add one to guide readers through a step-by-step walkthrough, explaining the organization of the site and distinguishing between references, guides, and learn area. This would also help surface areas that readers might not be aware exist, so help with discoverability. While readers eventually figure out the navigation and different parts of the site, the help menu could help with a quicker and easier onboarding process. Additionally, we could add more tours to highlight and explain features like the baseline.

[wbamberg]

These are pretty big sections, so I think they deserve more exposure.

How big they are isn't very relevant. The first thing to say is that these sections have very different audiences: while Glossary is, like most of MDN, for web developers, "Writing guidelines" is for contributors, who are a tiny fraction of web developers.

Putting "Writing guidelines" in the main menu (1a above) is just wrong for that reason, and might even be confusing for web developers (who might naturally think "writing" here refers to writing code).

1b is better, but why have 2 links here? I think a real problem here is that the metadocs are split between CONTRIBUTING.md and the docs under https://developer.mozilla.org/en-US/docs/MDN. See also mdn/content#31186 for a place this is a problem.

IMO it would be better to:

• migrate everything in CONTRIBUTING.md to somewhere under https://developer.mozilla.org/en-US/docs/MDN
• update CONTRIBUTING.md to point to https://developer.mozilla.org/en-US/docs/MDN
• update the "Learn how to contribute" link in the footer to point to https://developer.mozilla.org/en-US/docs/MDN

As for the glossary, I don't think it's a big problem that it's not linked. The glossary exists so we have a place to define things in other pages. IMO it's not a particularly big use case for people to decide to browse a glossary. But if we want it, then (3) is reasonable, although I would make the explanation text something like "Glossary of web development terms".

I recently proposed internally to add a "?" help menu button at the bottom right corner on the website. The help menu could serve as the home for glossary, contribution guide, and our writing guidelines.

For the same reason as before (different audiences), I think putting glossary in the same context as metadocs is a mistake. I think the existing "Learn how to contribute" link in the footer is enough for people to find the metadocs.

[OnkarRuikar]

I think a real problem here is that the metadocs are split between CONTRIBUTING.md and the docs under developer.mozilla.org/en-US/docs/MDN.

👍 Yes, we need to have everything on the hosted site and shouldn't send readers to GitHub for the info.

[bsmth]

👍 Yes, we need to have everything on the hosted site and shouldn't send readers to GitHub for the info.

I think most of this is done now, I did a sweep for links to contributing.md here:

• chore(contrib): Adding Bluesky, replace links to contributing.md content#39833

[estelle]

I agree that we need to have links to both the glossary and the writing guidelines.

Glossary

Suggestion: Add "glossary" to the reference drop down, as per Onkar's screen shot.
Explanation: When I used to look for a link to the glossary, I would always open the references drop-down, as that is where intuitively I felt it would be. Now to get to the glossary, I use the search. I enter "RGB" in the search as it's just 3 characters and I know the first or second result is the glossary term. I think a link from the reference drop-down is more intuitive ;)

Contribution guidelines

Option 1

Suggestion: Change the "Learn how to contribute" link in the "Help improve MDN" box to "Contribute to MDN", and have that point to an improved version of https://developer.mozilla.org/en-US/docs/MDN/Community/Contributing. Optionally add a "Learn how" after that, with the same URL as the current learn how to contribute.

Option 2

Suggestion: In the footer, add "Community Guidelines" with a link to https://developer.mozilla.org/en-US/docs/MDN/Community as the last item in the "Our communities" list and the "Contribute to MDN" link under any of the other 3 lists (either MDN, Support, or Developers)

Option 3

Suggestion: Do both Option 1 and Option 2

[OnkarRuikar]

In the community meeting on 27th March following things have been disussed:
a. TODO: Separate the discussions about writing guidelines and glossary.
Done. A separate discussion for glossary has been created.
b. It is not good that we have the guidelines at two places: GitHub readmes and hosted content on the website. It's not clear how to move Github readmes to content. There need to be something repo specific left in the GitHub readmes.
c. Estelle suggested that GitHub readmes are also markdown so they could be rendered as it is on the website. So there won't be any duplication. There could be implementation challenges though...
c. Mozilla team to get back later and convey the decision here.

[wbamberg]

It's not clear how to move Github readmes to content. There need to be something repo specific left in the GitHub readmes.
Estelle suggested that GitHub readmes are also markdown so they could be rendered as it is on the website. So there won't be any duplication. There could be implementation challenges though...

I was thinking we could just "CONTRIBUTING.md" say essentially "To learn how to contribute to MDN, please see https://developer.mozilla.org/en-US/docs/MDN/Community/Contributing". Why are we making things difficult for ourselves here?

[OnkarRuikar]

I was thinking we could just "CONTRIBUTING.md" say essentially "To learn how to contribute to MDN, please see developer.mozilla.org/en-US/docs/MDN/Community/Contributing". Why are we making things difficult for ourselves here?

Ruth said that if we do this for mdn/content repo then we'd have to do it for other repos as well and that is why in the past they decided to have each repo's guidelines in Github separately.
But I think mdn/content is the core repo and we should make an exception.

[hochan222]

I want to share experiences with the ko-locale for reference, as it might not be directly related to the current discussion. However, it's important that the CONTRIBUTING.md file remains easily accessible and not buried within the pages.

If you update or replace theCONTRIBUTING.md link in the footer for the writing guidelines section, I'm concerned that the CONTRIBUTING.md link accessible from the page might lead to a location too deep within the hierarchy. I hope the CONTRIBUTING.md link isn't too deep.

experience

I have experienced that more people than expected search for ways to contribute through Google, and that people refer to the blog more below than the first search result(https://developer.mozilla.org/ko/docs/MDN/Community/Contributing).

Link below image

Please see the blog posting date below. At that time, the CONTRIBUTING.md page for translated-content did not exist. To address this, I created mdn/translated-content#827 to guide potential contributors on how to contribute. However, it seems that contributors are primarily engaging through the 827 issue linked directly from the aforementioned blog post. I have received related 827 issue inquiries more than three times in the past week. You can also see that the inquiry was posted 2 days ago on the Discord Korean channel.

problem

Is it because the "Learn how to contribute." link has insufficient visibility? Of course, it is not a majority case, but it is happening consistently even in the current location(footer). Wouldn't it be a problem if the depth of access to the CONTRIBUTING.md link in the footer at the bottom of the page(including regular pages like background-color) deepens? Even if the link is moved, it would be good if it wasn't too deep.

[dipikabh]

c. Mozilla team to get back later and convey the decision here.

Hi @OnkarRuikar, we brought this up in our internal discussions. We're opting not to add the Writing Guidelines to the Guides menu, primarily to avoid any potential confusion for our web developer audience. However, we do agree and believe that there's a need to make the contribution workflow clearer and simpler. We will be reviewing how we link to the GitHub CONTRIBUTING.md vs our hosted contribution guidelines (and by extension, our writing guidelines) on the website.

[Rumyra]

Marking this as answered as the nav has been reorganised since the Fred launch - if there's any other concerns please open a fresh discussion