Mod Documentation/Manual Content & Format

[AlexB]

Writing documentation can take a good measure of time. Especially if you plan to do it for each and every unit. I don't know the nature of your mod, thus my thoughts can only be quite general. Maybe they don't even fit.

• Write the text without layouting the manual at the same time. Layouting distracts from writing and vice versa. If you layed out almost everything and then you encounter an item that doesn't fit the design, you'll have to rework all the things you already finished.
  
• Put information in the manual only once. Instead of writing the same stuff a second time, I usually refer to the other section. This makes it easier to change it afterwards. If you keep the same information in multiple places, chances are you forget about one when you are updating it.
  
• Don't give away too much. If you provide a comprehensive guide on how to encounter enemy units you provide a way to beat the game. Games are fun when they challenge you. If you can win the game by clicking buttons in the order explained by the manual, the game is boring. Let the players experiment. You could put the countermeasure information into a separate section, though.
  
• Add pictures. Using them to show your units is one way. But you can also use them as design element to break up long texts. Let the text flow around images. It makes long texts appear lighter. Walls of text scares readers.
  
• If you patch the mod to rebalance the units, you have to update the manual. Every sentence you type has to be maintained, too. You'll have to keep track of all changes. If you start writing the manual too early, you are risking many rewrites. (If you start too late, you risk to forget about features you wanted to mention. Keeping notes helps.)
  
• Use a consistent style, like consistent usage of active voice. "If the unit is double clicked, one ordered it do deploy." sounds strange, "Double-click the unit to deploy it" is correct also, but shorter and more up to the point. The player itself isn't the unit, no need to describe the action from its point of view. Also, don't mix "You can" and "The player can". Rule number one: don't reference the player as "the player".
  

You could put the story into the manual, too. Numbers are great, but they don't tell a story. For example, Ares has a rather technical documentation, thus it explains the "what", but not the reasons "why". It also doesn't explain the "how to". It tells about the small pieces. Games tell a story, the manual should put players in the right mood. Just give enough information so the player understands what's going on and why. The big picture. The game picks up from there and provides an interactive way to experience the story.

PDF is a good way to control the layout, because the document will look the same everywhere. One file contains everything. HTML is more dynamic, and quite lightweight. You can just put it on the web. Both have their disadvantages. PDF files usually open slower and pages are static. HTML looks different in different browsers and has no support for pages (but you can link between multiple files). You'll have to pick the most appropriate one that fits your needs best.