search

rertyy / pe

0 stars 0 forks source link

Missing doc for domain label #7

Open rertyy opened 2 months ago

rertyy commented 2 months ago

image.png

There is no mention of what a domain label is. You cannot expect the user to know the difference between domain label and domain name (I don't).

nus-pe-bot commented 2 months ago

Team's Response

Thank you for the feedback! We have explicitly mentioned the criteria that makes up a domain label (start and end with an alphanumeric character, separated by only hyphens), and have specified that a domain name is an entity made up of these domain labels separated by dots.

Items for the Tester to Verify

:question: Issue response

Team chose [response.Rejected]

Reason for disagreement: I believe you are missing the point.

Let's break this down.

Emails should be of the format local-part@domain...

This is clear. Although you could have explicitly demarcated what to look at with backticks e.g. local-part@domain.

Then you have a section which explicitly mentions local-part. This is also good.

The reader would then expect there to be a section to understand domain. But instead you jump into:

  1. This is followed by a '@' and then a domain name. The domain name is made up of domain labels separated by periods

Firstly, you do not explicitly mention that the whole thing after the @ is the domain name. (Note especially the word name is not mentioned previously, nor is "domain name" or "domain label" in a glossary).

Secondly, at no point do you mention what the "domain label" or "domain name" is, only what criteria the "domain name" and "domain label" must fulfill in order to be considered domain labels or domain names. Especially given the length of this bullet point, it is very difficult to link everything together. You're introducing jargon that the user is not expected to know, but you do not break down the jargon for the reader.

This is jumping a lot of hoops and unnecessarily obfuscates your documentation.

Let's contrast this with

Emails should be of the format local-part@domain [ ... ]

  1. This is followed by a '@' and then the "domain". The domain, also known as the domain name, is made of domain labels separated by periods. Each domain label is [ ... ] As an example, john@example.com