Mod Documentation/Manual Content & Format - Printable Version +- Renegade Projects Network Forums (https://forums.renegadeprojects.com) +-- Forum: Modding (https://forums.renegadeprojects.com/forumdisplay.php?fid=3) +--- Forum: Red Alert 2 & Yuri's Revenge Editing (https://forums.renegadeprojects.com/forumdisplay.php?fid=8) +--- Thread: Mod Documentation/Manual Content & Format (/showthread.php?tid=1879)

Mod Documentation/Manual Content & Format - Striker - 31.05.2011 Hi! As I am done with the planning stage and have 50% done of the coding, I now verifying my plan for a documentation/manual. Originally I had nothing special in mind, my question is now, which kind of documentation I should take and how detailed should it be? I have either HTML or PDF in mind. As usual for a manual, I would prefer PDF, as it feels, at least for me, more comfortable to do it in my writer program, but most mods have a documentation on their website. This is more accessible and users don't have to download a PDF. So I am really dissonant regarding this. Another question I ask myself is, how much work should I put in this documentation? In which facts are people interested? For the units section, I use a format which tells the cost, the prerequisites and its armor type. In a short description, I tell of its speed, its range, the armor types it's good against, land/air targeting, the IFV function and if available, whats its use, if the unit is deployable. After that, I give some examples of possible designated use (use it for eco-bash, against Air, ...). Then I give examples of countermeasures for every of the three sides. I'm also planning to include a "Strong/weak against" with some prime examples. Is this enough, too much, too less or are there specific details I should think about? I hope you can help me with these questions (as a documentation reader or as a writer) with serious advice. Thanks in advance RE: Mod Documentation/Manual Content & Format - Graion Dilach - 31.05.2011 Well, I think the Mental Omega webpage is a great example of mod documentation. Maybe you can only document the changes and drop out background stories. RE: Mod Documentation/Manual Content & Format - AlexB - 31.05.2011 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.