Re: [dns-wg] DNS migration draft - new version

[Brad Knowles <]

At 9:58 AM +0100 2004-09-22, Fernando Garcia wrote:

	Almost all the issues I have here have to do with the writing, 
not the technical details.  I'm not a technical writer myself, but I 
hope you aren't offended if I make some suggestions.

	In general, you want to change passive voice into active voice 
throughout the document.  Using passive voice makes reading the 
document much more difficult, which means you'll have to spend a lot 
more time writing and re-writing and re-re-writing to try to make up 
for the problems it introduces.  If you change everything to using 
active voice, this should be less of a problem.


	If you have access to good writing analysis tools (including 
grammar, usage, mechanics, style, and organization), they can give 
you suggestions which can help with this process.  However, I'd also 
suggest that you try to find a good technical writer who has a native 
command of the English language (or native equivalent).

	Software might be able to help you solve the easy 80% of the 
problems in this paper, but nothing beats a good technical writer who 
understands the reasoning behind the rules and knows when and how to 
break them, in addition to knowing the basics of things like Strunk & 
White or the Chicago Manual of Style.

	I know of these things, because I have met real technical 
writers, although I am not one myself.

>  Given this is not a situation network or systems administrators need to face
>  off, it is common to make mistakes when undertaking the migration process,
>  mistakes which could be fatal for the services depending on the DNS service.
	I think you meant "... face often", not "... face off".

>  3.1 Control over the new DNS server
>
>  It is compulsory that the person in charge of the domain migration or any
>  other person under his/her supervision must have control over the contents
>  and operation of the DNS server that will contain the domain information at
>  the end of the migration.
	This paragraph seems confusing to me.  Let's try re-wording this slightly:

		The person in charge of the domain migration, and all persons
		under his/her supervision, must have control over the contents
		and operation of the DNS server that will contain the domain
		information at the end of the migration.

>  3.2 Overlapping in time IP ranges
>
>  This procedure requires both ranges of IP addresses to be active
>  simultaneously during the migration.
	Again, remove the first bits and re-word:

		Both ranges of IP addresses must be simultaneously active
		during the migration.

>  3.3 Guarantee authority with the corresponding NIC
>
>  This person responsible for the migration must be registered in the NIC and
>  must be the administrative or technical contact with permission to make
>  changes in the domain information, specially the host name and IP of domain
>  servers.
	Re-word:

		The person responsible for the migration must be registered with
		the NIC as the administrative and/or technical contact, with
		permission to make changes in the domain information, specifically
		the host name and IP address of the domain name servers.

>  3.4 Minimal DNS knowledge
>
>  Though is not compulsory a in depth knowledge of the DNS protocol and its
>  implementations, it is necessary a minimal understanding of it's
>  fundamentals and the working of the implementation used.
	Re-word:

		Although this procedure does not require in-depth knowledge of
		the DNS protocol and its implementations, it is necessary to
		have a minimal understanding of DNS fundamentals and the
		the implementation used.

>  3.5 Plan in advance
>
>  To avoid problems with time expiration and with incorrect data in the cache
>  as explained previously, the changes must be started with enough time.
	Re-word:

		The process must be started early enough so that you can avoid
		problems with old data persisting too long, or new data not being
		propagated quickly enough.

		Once everything else is in place and ready to go, handling the
		changes at the registrar can usually be accomplished in two weeks,
		if you have followed the standard DNS values recommended by RIPE.

		If the other aspects of your transition will take longer than two
		weeks, you need to adjust your schedule so that they will be
		complete in time for the changes to have taken place at the
		registrar.

>  3.6 Duplicate DNS servers
>
>  This migration plan forces that the hardware used by the DNS servers to be
>  independent of the hardware used by the other servers, so the change of
>  network configuration of this servers can be made without impact on the
>  other services.
	Re-word:

		This migration plan requires that the hardware used by the DNS
		servers is independent of the hardware used by the other servers
		and services to be transitioned, so that the change of network
		configuration on these servers can be made without impact on the
		other services.

		Also, to ensure the stability of the services, these DNS servers
		must be duplicated during the transition (and presumably some
		time before and after), so you will need duplicate machines.

>  3.7 Duplicate other services' servers
>
>  This will allow not only the domain to be visible all the time, but also the
>  services to keep running all the time.
	Re-word:

		This will not only allow the domain to be visible at all times
		throughout the transition, but to also keep the services running
		during the entire transition.

>  If you don't use duplicate servers, during the migration of the servers from
>  one IP range to other -even if there is no physical movement- you get a
>  shutdown of the services.
	Re-word:

		Otherwise, you will suffer a shutdown and lack of availability
		of services during the transition.

>  3.8 ISP coordination (and cooperation)
>
>  Though it's possible to make the migration without the cooperation of the
>  administrator of the old DNS service (in many cases is an ISP that is losing
>  a customer) and sometimes it's the only way to go, we recommend looking for
>  the help of both DNS administrators.
	Re-word:

		This kind of transition frequently occurs because you are moving
		from one service provider to another.  In these cases, you may
		not be able to get much assistance from the provider you are
		leaving, but this process is likely to be much more difficult
		without the help of both providers.

		Ideally, it should be a part of your written service contract
		that your old provider must provide any and all assistance you
		require during such a transition.  If you do not currently have
		such a provision in your service contract, this would be a good
		time to get it amended.  You certainly want to make sure that
		this provision is a part of the service contract with your new
		provider, should you ever have to go through this process again.



	And that's about as far as I've gotten so far.  Many more hours 
of polishing and wordsmithing should be applied before this thing 
actually goes out.


--
Brad Knowles, brad@localhost

"Those who would give up essential Liberty, to purchase a little
temporary Safety, deserve neither Liberty nor Safety."

    -- Benjamin Franklin (1706-1790), reply of the Pennsylvania
    Assembly to the Governor, November 11, 1755

  SAGE member since 1995.  See <http://www.sage.org/> for more info.