Writing a guide for every game, checked against the code

Since 7 October, every game page on PLAYPILE has a full written guide under the game: how it plays, tips, what is in it, and answers to the usual questions. As of today that is all 33 games, including the thirteen we added today. This post explains why we started, how a guide gets written, and the slightly embarrassing number of mistakes the process found in our own pages.

Why: the pages were empty

On 7 October our application to show adverts was turned down for "low value content". Every game had a description, a list of controls and a tip. But when we looked at what a reviewer or a search engine actually receives, the verdict was right.

Each game page was the same template. Where the title should be, the file said GAME, and a script filled in the real title, description and controls after the page loaded. A person in a browser saw a full page. Anything reading the page source saw the same empty shell, once per game. We had built a site that looked substantial to people and thin to everything else.

There were two fixes, and we made both.

Fix one: put the words in the page

The build step that assembles the site now writes each game's title, description, controls, guide and links directly into that game's page. It does this with the same functions the page uses in the browser, so the text in the source and the text on the screen cannot disagree. The template carries named markers, and the build replaces each one with the real content. If a game has no guide, the build prints a warning saying so, which means a new game cannot quietly go live without one.

The same pass tidied up two related problems. Games taken off the site are now deleted from the build entirely, because an orphan page that nothing links to is exactly the kind of thin page a reviewer marks down. And the categories became real pages, each with a short introduction and every game in it, instead of a filter applied by a script.

Fix two: write something worth reading

Putting the existing short descriptions into the source would have helped, but three sentences per game is still not much. So every game got a guide of roughly 450 to 750 words, in the same four parts:

• How to play: the rules and controls in plain sentences.
• Tips and strategy: advice that comes from how the game actually works.
• What's in it: the modes, levels, unlocks and settings.
• Questions: the things people ask, such as whether it works on a phone and where scores are kept.

The rule that matters is the second one. A guide is written from the game's own code, not from memory, and then checked against the code a second time before it goes up. If a guide says something, the game has to do it.

An example: SWEEP

Take SWEEP, our minesweeper against a clock. Its guide says the first click on every board is always safe, and so are the eight squares around it. That is true because the game only lays its mines after your first click, away from that square and its neighbours. It says each cleared square is worth 2 points, and a cleared board adds 60, plus 3 for every second left and 2 for every mine. Those are the numbers in the scoring code.

The most useful tip in it, "take a look first, because the clock does not start until your first click", only became true on 7 October. Before that, SWEEP had two clocks that disagreed: the countdown started when the board appeared, and the leaderboard time started at your first click. Now both start at the first click. That is the fairer rule, because there is nothing to read on a board before it, so seconds spent before the first click are not seconds spent playing. The same day, the board sizes were put in order from smallest to largest.

What the checking found

Writing guides against the code is a slow way to read your own game, and it found a lot. Many of our short descriptions and control lists had fallen behind the games. Games had been changed and their pages had not. Some of the text fixes from that day:

• HIGHRISE needed its floor count and weapon list corrected: there are thirty-one floors, and the flare gun is the ninth weapon.
• In KICKBACK, the Slug upgrade was described in the game as firing one ball, while the code fires two. The words were changed to match the code, not the other way round.
• Wrong text was also fixed in APEX, QUICKDRAW and PIPEWORKS.

None of these were dramatic. But each one was a page telling a player something false about a game, and nobody had noticed, because the person who changes a game is usually thinking about the game, not the paragraph that describes it.

A guide is part of the game now

We now treat a wrong guide as a bug, and the About page says so. When a game changes, its guide is part of the change. When a new game is added, its guide is written and checked against its code before the game goes live, which is why today's thirteen games arrived with their guides already in place.

On the same day we also took seven of the older, simpler games off the site, and played every remaining game through again by hand.

Whether this is enough for the advertising review, we will find out. But the site is better for it either way. A guide that has been checked against the code is the closest thing a browser game has to a manual.