I have read the "New Rules" and offer the following (hopefully constructive) criticisms as a technical author:
- Domain Name Definitions
I believe that this is technically flawed in its current form. As shown "our" is a 'hostname' in the domain of 'sample.co.uk'. In fact, I do not believe that you can (sensibly) have an example without the explanation of a hostname versus domain name since the norm is to have a host as the most left-hand part of the construct.
So,
our.sample.co.uk
is like
www.sample.co.uk
and 'www.sample.co.uk' isn't a domain (usually) - in fact there's no reason why 'our.sample.co.uk' couldn't be running a webserver on port 80 - as it is a host...
It would probably be beneficial to re-word/re-write the definition and introduce 'hosts' in 'domains' perhaps expanding a little and adding something like:
sales.sample.co.uk
accounts.sample.co.uk
production.sample.co.uk
using 'departments' by way of example to show the concept of sub-domains but still show the hosts in those domains, for example both sales and accounts might have a web-site in the form:
www.sales.sample.co.uk
www.accounts.sample.co.uk
This would, by way of hi-lighting, then allow you to clearly show the part of a domain/host name that you are referring to as TLD, SLD and sub-domain.
- Define definitions before use in documents
Reading the document strictly "top to bottom" it fails the test of reading a definition before it is used for the first time - examples "Closed SLD", "Open SLD" etc. This is probably okay when you are writing to an audience that already understands the subject content, but is not good style.
Use the proper English way to introduce abbreviations, that is on the first occasion you say "Second Level Domain (SLD)" and then throughout the document can then just refer to it as "SLD" - why Upper Case and lower case versions with/without double quotes?
- Too much gobbledygook
Explanation of permitted characters in a third-level domain name is too complicated and repeated (with different style in section on distilling long Ltd and Plc names).
Why can you not simply say:
- may be a maximum of thirty-seven (37) characters long
- must be at least two (2) characters long
- may contain lower case Roman letters 'a'-'z'
- only base-letters are allowed (no accents, graves, acutes, etc.)
- may contain numbers Arabic numbers '0'-'9'
- may contain single hyphens (but not at the start or end)
- must start with a letter
- may not contain other punctuation
- two character long domains must contain a letter and a number (not two letters or two numbers)
Give a concise set of examples, for example:
Unacceptable:
a.co.uk
aa.co.uk
-a.co.uk
a-.co.uk
-.co.uk
--.co.uk
--9x9--.co.uk
9x9.co.uk
!splat.co.uk
this-domain-name-is-far-too-long-for-its-own-good.co.uk
double--hyphen.co.uk
Acceptable:
k9.co.uk
sample.co.uk
fred-smith.co.uk.
Generally a short, concise, description with clear examples works better than lots of words.
When you define the procedure you use to distil a long Ltd or Plc name you can refer to the requirement that the final name must still comply to the name definition in section 1.x
- How I'd improve the Rules
I recommend moving all the definitions to the top - how about:
- Definitions
This section defines terms used throughout this document and technical requirements....
1.1 We, Our and Us
The terms "We", "Our" and "Us" refer to ... xxxxx (this is a definition and
should be in the definitions section)
1.2 Domains, Sub-domains, host names
<describe>
1.3 Permitted characters, valid and invalid domain names
<single concise main definition>
1.4 Open and Closed SLDs
Say what they are before using them in the document (avoid forward references).
The term "Open SLD" refers to a domain that may be registered by....