Changing a site without starting it again

The turn you are aiming for

By the end of this lesson you should be able to send a change and get back a site where the one thing you named is different and nothing else has moved. That is a repeatable outcome rather than luck, and almost all of the work is in the sentence.

Every turn after the first is a change turn, and the builder is already set up for it. It is told to touch only the files that actually carry the change, to edit a file rather than rewrite it where an edit will do, and to keep everything it was not asked about exactly as it was. The reason given is your reason: an unrequested change is a bug from your side of the screen, because you now have to review something you never asked for.

So it is not looking for an excuse to redecorate. When a change lands wider than you meant, the sentence nearly always failed to say one of two things — which thing, or what should stay.

• It reads your words against the site as it actually is. "The bit at the top" and "the boxes in the middle" are positions on a page, and it is told to find them in the real markup rather than trusting a file name.
• It is told to search before telling you something is not there, which is the answer that most makes a builder look like it is not listening.
• Files that do not change are left alone rather than tidied.
• Your standing preferences carry across turns. "No stock photographs" or "keep it plain", said five turns ago, is still part of the brief now.
• A turn that wrote files ends by naming what changed in two or three plain lines.

Note. None of that is a promise every turn lands. It is what the turn is aiming at, which is the useful part — it tells you exactly what your sentence has to supply, and what you can leave out.

Two kinds of turn, and how yours gets chosen

There is no switch for this. Whether a turn changes the site you have or starts something new is decided by what your message looks like, and you can predict it once you know what it is reading for.

A message that names a place is a change, and only the files carrying that place are touched. A message that names no place at all is read as a complete brief about the whole page. "Do better", "it looks cheap", "this is boring" are not treated as vague and queried back at you — they are treated as an instruction to find whatever is most visibly weakest and raise it, wherever on the page that turns out to be.

That is often exactly what you want. It is rarely what you want at half past four when one heading is wrong.

And a message that reads like a first brief gets built like one. Typing "a modern site for a fencing company in Norwich" into a project that already has a site is a description of a site rather than a description of a change, and what comes back is a site.

Tip. If what is wrong is the whole feel of the site — the tone, the sense that it belongs to a bigger company than yours — say the general thing once with no target and let the page move together. Patching a tone paragraph by paragraph leaves you with a site that argues with itself.

Name the place and the change in the same sentence

Your instruction is read as four things. You can hand over all four in one ordinary sentence without sounding like you are filling in a form, and knowing the four is what stops you leaving one out.

The four parts of a change

The place

Where it is, in the words you would use pointing at the screen. The page first, then the thing on it. Plain words beat design words you half know, because you will not be able to check the result of a sentence you did not fully mean.

The operation

The actual verb, and it will not be swapped for a near one. Replace is not crop, move is not resize, remove is not hide. Ask for the one you mean and you get the one you mean.

The result

What it should be like afterwards, described so you could confirm it by looking. Not better — shorter, wider, above the photograph, in six words.

What stays

Five words carry real weight here: do not, keep, leave, except, preserve. Any of them marks something as a hard no-change target, even in a sentence that also asks for a change.

What "it" means

A pronoun counts as a place, and it resolves to the last thing discussed or changed. If the previous turn touched the pricing section and you now say "make it bigger", it means the pricing section.

That is convenient when it is what you meant and expensive when it is not. The moment you have moved on to something else, name the thing rather than pointing at it.

When your sentence has two meanings

Where two readings differ materially, the turn is told to take the smaller and more reversible one and say in a line which it took. So an ambiguous sentence does not usually produce a disaster. It produces a modest change and an explanation, and you correct it in one more turn.

This is why describing the outcome beats guessing at the mechanism. "Nobody can find the phone number on a phone" leaves the fix open to whatever is actually in the way. A guess at what to change narrows the fix to your guess.

The same request, before and after

None of the rewrites below are longer than a text message, and none of them use a word you would not use on the phone. What each one adds is a place, the right verb, or the part that must not move.

Note. Read the middle column out loud. None of it is technical and none of it names a file. That is the register to write in — the builder is mapping your words onto the markup itself, so plain words about the page are worth more to it than half-remembered words about the code.

One thing at a time, and when that stops mattering

Three changes in one message works. Nothing forbids it and most of the time you get all three.

The cost is that you can no longer tell which of your three sentences produced the bit you did not like, and going back takes all three with it — the two that landed as well as the one that did not. Three separate turns cost about the same in total and each one comes out on its own.

So batch them when the changes are unrelated and you are confident about all three. Split them when you are being fussy about layout, when two of them touch the same part of the page, or when one of them is the change you actually care about.

1. Look at the page and say where it is, in your own words. The page first, then the thing on it.
2. Say what should be different about it, in a way you could confirm by looking.
3. Add the part that must not move, using one of the five words that carry weight — do not, keep, leave, except, preserve.
4. Send it on its own.
5. Read the last two or three lines of the reply. That is the receipt, and it names what somebody looking at the page would notice rather than which files were touched.
6. Look at the page yourself and check both halves: the named thing changed, and the named thing that should not have changed did not.

Tip. If you find yourself sending the same complaint twice, the second one is not being misunderstood. It is being answered on top of the first attempt, and every round after that answers the round before rather than your original problem. Go back to the version before it and say it once, differently.

Asking for more is where invented facts get in

Most change turns are asking for more of something. More detail in the services, a longer about section, a proper set of questions and answers at the bottom. That is depth, and depth is exactly where a made-up specific is easiest to reach for, because a sentence with a number in it reads better than the same sentence without one.

So the rule against inventing gets stricter on these turns rather than looser, and it is written that way deliberately. The turn that deepens a whole page says so in as many words: the rule gets harder here, not easier, because depth is what is being added and invented specifics are the easiest depth there is.

In practice one of two things comes back. Either the section is written so it does not need the figure you never supplied, or there is a plainly marked placeholder and one line saying what it needs from you.

That is the correct behaviour, and it is also the thing that makes people think a turn failed. A marked placeholder is not the builder running out of ideas. It is the builder refusing to put a phone number on a real business's live site that nobody has checked.

• A phone number, an email address or a street address.
• A certification, a registration number or an insurance policy.
• A star rating or a review count.
• A years-in-business figure.

Tip. Send the facts with the ask, in the same message. "Make the about section longer — we started in 2013, there are two of us, and we cover Norwich out to about twenty miles" gets you the depth in one turn instead of a placeholder and a second turn.

Note. Prices do not behave like that list, and the difference catches people. Where you supplied nothing real, plausible prices get written in so the page is not full of gaps, and they look exactly as real as everything around them. Check any figure you did not supply before you decide a section is finished. The next lesson takes that apart properly.

How to tell it worked

A turn that wrote files finishes with two or three plain lines naming the changes — "the header stays put when you scroll now", rather than a list of file names. The files are already listed under the reply by name, so those lines exist to tell you what the change was for.

Read them against the page rather than accepting them. A change named in the reply that you cannot find on the page is a change that did not happen, and that is far better caught now than a fortnight later.

1. Find the thing you named and confirm it is different in the way you asked for.
2. Look at the part you told it to leave alone. This is the step people skip, and it is the one that catches a wide change early.
3. Look at the page at phone width as well, if the change was anywhere near the top.
4. Read any number, name or detail that appeared and that you did not supply. Take it out now rather than after somebody rings about it.

Note. If a turn went somewhere you did not want, do not argue with it. The site as it stood before the turn is kept, and restoring it is one press. The page on when a build goes wrong is about exactly that, and reading it before you need it is the difference between one wasted turn and four.

Common questions

Will it change my colours if I only asked about the header?

It should not. It is told to touch only the files that carry the change and to leave the rest exactly as it was, on the grounds that an unrequested change is a bug from your point of view. Where it happens anyway, the usual cause is a sentence with no place named in it, which is read as being about the whole page.

Do I have to name the file I want changed?

No, and trying usually makes it worse. A header can live in a file called anything at all, so the builder is told to map your words onto the real markup rather than trusting a file name to match. Say where the thing is on the page and let it find the file.

Does a small change cost as much as a full build?

No. A turn is charged for what it actually uses, so rewording a line sits near the minimum and a first full build is the expensive one. The figure for each turn is shown against the reply that produced it, so you never have to estimate.

It says it did something and I cannot see it. What now?

Check you are looking at the right page of the right site, and reload. If it genuinely is not there, say which reading was wrong rather than sending your original sentence again — repeating yourself is what starts the loop where every round answers the round before it instead of your problem.