Update index.html

[UnityOfFairfax]

Although not necessary in an <li> element, a <p> adds a little space in between each list item. This can make a lists of steps a bit less intimidating (which is important when the list of steps is directed at newcomers).

[Elchi3]

Hey, thanks for your PR. I don't think we should do this. If the list styling generally doesn't provide enough space, then that's an MDN CSS / front-end issue (cc @schalkneethling)

[UnityOfFairfax]

I don't think we should do this. If the list styling generally doesn't provide enough space, then that's an MDN CSS / front-end issue

Well, I'm not saying the issue is with spacing of list items across all MDN docs. I'm saying that this particular list benefits from the change.

It makes sense from a semantic markup point of view as well, if you think about it.

There is a difference between a list of short-form content like “milk, eggs, butter”—or, more appropriately, “HTMLElement, HTMLTableElement, HTMLSpanElement”—and a list of instructions, where each list item contains medium- or long-form content.

These instructions include more than one sentence per list item. Although I referenced spacing, I don’t think that, at its core, this Pull Request implies a CSS issue; it reflects a semantic difference between a list of short-form items and a list of medium- or long-form items.

[Elchi3]

Okay cool, thanks for elaborating! Re-opening so that we get a second reviewer's opinion here.

[UnityOfFairfax]

Thank you for reconsidering! 🙏

[Elchi3]

Forgot to request a secondary reviewer here, sorry. Did that now.

[chrisdavidmills]

Hi there,

If you look at the current state of the page — https://developer.mozilla.org/en-US/docs/MDN/Contribute/Getting_started — you'll see that it is very different to how it was when this PR was originally filed, so this is no longer relevant. sorry about that @UnityOfFairfax ! We get to most PRs in a timely manner, but we have a lot of activity on here, and some do slip through the cracks.

For future reference, I don't think you are wrong, but I'd like to advise against this kind of change. First of all, consistency is important in documentation, and doing this on one page would then mean a lot of work hunting down suitable lists on other pages and making the change there too. Which brings me on to my second point — there are much bigger problems to fix on MDN right now, so I like to point people towards our issue backlog to fix some of the out and out errors we've got, before concerning themselves with minor semantic improvements (which I do think have value, but I think our semantics are generally "good enough").

Thanks you again for your interest in contributing. If you are interested in helping to fix some bugs, I'd be more than happy to help you get started.

I'm closing this now, but feel free to chime in further.

[UnityOfFairfax]

For future reference, I don't think you are wrong, but I'd like to advise against this kind of change. First of all, consistency is important in documentation, and doing this on one page would then mean a lot of work hunting down suitable lists on other pages and making the change there too.

I know it sounds crazy, but I'm actually happy to do that sort of work. Up until quite recently, I used to—back when MDN was a wiki.

Which brings me on to my second point — there are much bigger problems to fix on MDN right now, so I like to point people towards our issue backlog to fix some of the out and out errors we've got, before concerning themselves with minor semantic improvements (which I do think have value, but I think our semantics are generally "good enough").

I can appreciate that.

I am also passionate about improving MDN docs.

Is there any way I can continue helping MDN without investing a lot of time into rejected PRs?

I keep running into the following barriers that make it harder and harder for me to continue trying to contribute:

1. I feel a bit paralyzed between offering small Pull Requests that get rejected because of “If we do it here, then we’ll have to do it everywhere” and offering large (for the sake of consistency) Pull Requests that get rejected because of “This is too large to review; please open small Pull Requests instead”. (My main account is @Zearin, under which I have also made some PRs.)
2. A look through your Issues backlog shows many issues related to broken links (probably due to the recent MDN migration), examples that don’t work (or have browser compatibility problems), and correctly documenting inheritance of object hierarchies.

• I can’t offer much help with most of these. (If someone can provide me with a step-by-step procedure for checking/fixing the hierarchies, I would be glad to start going through them.)
• I am an efficient editor when it comes to improving the clarity of phrasing, using formatting to support communication of ideas, and lots of “minor” edits that seem trivial on their own, but together can add up to a decent improvement for the reader. Given the backlog, it seems like this type of edit will always be rejected as unimportant.
• I would like to convince someone on the MDN content team that these can add up to something that is important. But even if I fail to convince anyone, I would like to find some category of issue to help out. Editing comes naturally to me, so it doesn’t use too many brain cycles for me. But if there is a type of task that has a known solution, but people are reluctant to do because they find it tedious—such as checking every page within a category of docs for consistency in some form, or verifying that object hierarchies are correctly linked to one another—this is the sort of thing I take pleasure in doing.

Can you help me find a good fit for contribution to these docs?

[Ryuno-Ki]

@rachelandrew Could you need help on #1712 ?

Usage and examples section could be a bit „risky” (or: take more iterations to get right), but the structure would be akin to #1714 I think.

@UnityOfFairfax / @Zearin Is this something you'd be willing to pick up?

[chrisdavidmills]

@UnityOfFairfax thanks for explaining your feelings on contributing to MDN, and giving us an idea about what kinds of work you feel like you could be most useful for. This is really useful to me when trying to figure where best to place you.

In terms of small fixes, I am happy to accept PRs on things that are out and out wrong, even if they need to be fixed on a number of pages. I just felt that this one more of a minor improvement, than a fix, and that there are more important things to worry about. If you see some items that you think might be good semantic fixes but you are not sure, then you can feel free to open an issue to discuss them first before submitting PRs.

I also had another idea — we soon intending to continue on a project to make all our reference pages more consistent, which would involve writing recipes that define what structure each page should have, and then updating a bunch of pages to make them conform to that defined structures. This sounds like something that you might find interesting.

[Zearin]

(I should probably switch to my personal account, so I’ll stick with Zearin from now on...)

@UnityOfFairfax / @Zearin Is this something you'd be willing to pick up?

I think so. What is the preferred way I should proceed?

[Zearin]

I also had another idea — we soon intending to continue on a project to make all our reference pages more consistent, which would involve writing recipes that define what structure each page should have, and then updating a bunch of pages to make them conform to that defined structures. This sounds like something that you might find interesting.

@chrisdavidmills: I do find it interesting. Can you tell me more? :)