Improve Web/API/Document/images

[leon-win]

Description

This PR updates Web/API/Document/images. List of changes:

• replace link to HTMLImageElement instead of constructor,
• improve example description,
• remove unnecesary line breaks.

[github-actions]

Preview URLs

• /en-US/docs/Web/API/Document/images

(comment last updated: 2024-05-19 23:58:06)

[hamishwillee]

Thanks @leon-win

I'll merge this one, but as a general rule MDN does not accept layout-only changes or "to my taste" changes on their own. The reason is that the changes do not affect the rendered content, but they do take time to review, and the time the reviewer team have is limited.

We do however accept technical fixes, and grammatical fixes etc that remove ambiguity, and so on. So you are more than welcome to add a technical fix, and as part of that also tidy layout.

[hamishwillee]

Ah, @leon-win Reading this more carefully, your change was technical - removing the constructor link. Apologies.

W.r.t. line breaks there are no firm rule on how these should be done in MDN. Most of the reviewer team strip out line breaks within a sentence. I tend to split on sentences.

[leon-win]

Ah, @leon-win Reading this more carefully, your change was technical - removing the constructor link. Apologies.

W.r.t. line breaks there are no firm rule on how these should be done in MDN. Most of the reviewer team strip out line breaks within a sentence. I tend to split on sentences.

Hello, @hamishwillee! Thank you for review and comments!

Yes, I made two changes (about the constructor and about the example) and at the same time decided to remove line breaks))

I agree that this is a matter of taste.
In my opinion, using an autoformatter (if possible in this case) would eliminate ambiguity and reduce the burden on reviewers.

[hamishwillee]

In my opinion, using an autoformatter (if possible in this case) would eliminate ambiguity and reduce the burden on reviewers.

@leon-win IMO the ambiguity only matters if it affects the rendered output, which it does not. IMO not worth the churn to do automatically. This is one of those things where people have strong opinions: I'd be pretty happy if we all agreed to break on sentences, but if the agreement ended up being "break on 80chars" I would cease working on MDN :-)

[leon-win]

@leon-win IMO the ambiguity only matters if it affects the rendered output, which it does not. IMO not worth the churn to do automatically. This is one of those things where people have strong opinions: I'd be pretty happy if we all agreed to break on sentences, but if the agreement ended up being "break on 80chars" I would cease working on MDN :-)

The 80 character limit is more suitable for the Python language)) Therefore, stay in MDN 🤗

And about moving sentences to a new line. To be honest, I don’t really like this, precisely because these line breaks are not in the resulting display. And if we want to make a semantic emphasis, to separate parts of the text, then we need to make a break in the form of a separate paragraph, it seems to me so.

But now, seeing such line breaks, I will remember our conversation and try not to delete them =)

[hamishwillee]

Appreciate you not deleting them. I have several reasons for this approach.

1. Some years ago I was working with translators and they preferred sentence to paragraph breaks. That is probably tool-specific.
2. When reviewing in Github it is more likely to be able to have fixes constrained to a sentence than a paragraph - that just makes seeing the changes easier. Smaller lines obviously make this even easier, but I don't like those.
3. When I review, I read line by line, and it makes it easier for me to parse carefully. Again, this is a "me" thing.

I can live with paragraph breaks. There are many who are not convinced my approach is better.