4

IS it acceptable to use HTML comments(<!--TEXT--!>) in posts as signals that can be seen by other editors in order to clarify info to future editors, but things that should not be shown on the post as it is unnecessary there?

Example:

When one edits, they see something that they are unsure of the meaning of(unclear, but looks salvageable) and when they make it clearer, they put a comment to other editors that they extrapolated it this way.

This is easier than the edit description as it is directly seen by other editors. Is this acceptable?

  • 2
    I would think it is not only acceptable, but an AWESOME idea. I'm not in a position of authority though, so this is just a comment. – RobotHumans Jun 15 '12 at 22:17
  • 2
    I'm not just soliciting responses from mods, but I welcome their input. – hexafraction Jun 15 '12 at 22:47
4

I'm not a moderator, and this is just my opinion.

I think it is acceptable to do this, and good to do it when it makes sense. But I think that situations where it makes sense to do this are not extremely common. Here are what I consider a couple good use cases for this.

Explaining Why Something Should Stay The Way It Is

I have done this myself in the past, to clarify the reason for long alt text describing what can clearly be seen in the image. (I was encouraging future editors to retain the alt text because it made the post accessible even to people who could not use the image.)

Similarly, if a post was a derivative work of free content that required attribution, and editors had been failing to retain the attribution, I would likely add such an HTML comment explaining why the attribution needed to be retained.

If a post contained more complex HTML syntax that was necessary for it to be formatted properly, and editors were converting it to markdown syntax that lost subtle but important formatting, I would add an HTML comment about this as well.

Explaining Why Something Should Be Changed

Requests for editing to improve a post should probably never be made just in HTML comments, but they could reasonably be expanded on in HTML comments, for the benefit of people actually attempting to make the requested changes.

Communicating With Editors Approving/Rejecting/Improving Suggested Edits

As a very different scenario, I agree with aking1012 that HTML comments make sense for edits that are subject to approval, to clarify the reason for a change that might not be obvious, or to annotate a change that the low-rep editor is pretty sure but not totally sure is correct.

I have approved edits that included this, and been grateful it was included. In at least one instance, I left the comment, to account for the small possibility that both the author of the suggested edit and I were making a mistake.

With that said, I do have one concern about this: If someone just approves (or rejects) a suggested edit, do they ever actually see these HTML comments? The post is shown to editors as it appears (i.e., the raw code, whether it be HTML or markdown, is not shown), so editors will only see it in edits they think are worthy but need improvement.

Therefore, unless I am mistaken about how this works, in suggested edits this should probably be limited to providing information that is specifically useful when improving the edit, but which would not affect the decision between Approving as-is, approving and editing (i.e., Improving), and Rejecting.

Explaining How Information Was Obtained From The OP

When I edit a post to include information the original poster provided in comments, chat, an "answer" that should have been an edit, or elsewhere, I explain where I got the information in the edit summary.

While I have yet to encounter this situation, I would imagine that sometimes an edit is sufficiently complex that the edit summary, while still important, would not explain how each piece of information was gleaned from the OP. In these scenarios, it might make sense to include some HTML code comments next to specific text, explaining how it was obtained.

Please note that I am not saying HTML code comments should be used for attribution. Rather, I am saying that, in moderation, HTML code comments may be used as annotations to enhance (not replace) the information provided in the edit summary.

I do not think this particular situation happens often.


There are also some general kinds of scenarios where I think HTML code comments shouldn't be used.

Information that is likely to be useful to the following groups of people should not, in my opinion, be relegated to HTML code comments:

  • The original poster.
  • People using the post (e.g., answering the question, using an answer, voting).
  • People considering editing the post, as they will probably not see the source until they decide to edit it.
  • People deciding whether or not to close the post or flag for moderator attention.
  • Moderators, unless they have specifically requested information be conveyed to them in this way.
  • People creating derivative works of the post not on Ask Ubuntu, as they might never actually see the source code (they might copy-with-formatting the formatted text).

Furthermore, when a post is a derivative work, attribution should never be just in HTML code comments; it should always be visible to whoever reads the work (and thus probably doesn't need to be in HTML code comments).

2

I would think it is not only acceptable, but an AWESOME idea.

It gives a way for editors to drop notes to other editors that might have a better understanding of the question at hand, without just waiting for something to be seen.

Another bonus of this approach could be if a low-priv/rep editor didn't fully grasp the issue at hand, but was REALLY trying to help out a LOT.

Just my thoughts....

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .