The internet is a lawless place with knowledge and sarcastic wit the pistols of this wild frontier.
Don't go out without being sufficiently armed.

~Blade

Other places

Ares (Current version: 0.B)

Ares's primary facilities have been moved elsewhere:

  • If you wish to report a bug in Ares, please proceed to its bugtracker.
  • If you'd like to request a feature, register a blueprint.
  • If you have questions or can provide answers regarding Ares's usage, visit the Q&A section.
  • Before you post a new question, you should check the FAQ, though.

Behavior

  • Mind the forum rules.
  • Due to its documentedly horrible quality, we do not offer NPatch support.


Post Reply 
 
Thread Rating:
  • 0 Votes - 0 Average
  • 1
  • 2
  • 3
  • 4
  • 5
Mod Documentation/Manual Content & Format
Author Message
Private Striker Offline
Junior Member
**
Members

Posts: 25
Joined: 27 Oct 2006
Reputation: 0
Post: #1
Mod Documentation/Manual Content & Format
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
31.05.2011 14:28:30
Find all posts by this user Quote this message in a reply
Ares Tester Graion Dilach Offline
Senior Member
****

Posts: 317
Joined: 2 May 2010
Reputation: 3
Post: #2
RE: Mod Documentation/Manual Content & Format
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.
31.05.2011 15:31:17
Find all posts by this user Quote this message in a reply
Ares Tester AlexB Offline
Grandmaster B
***

Posts: 221
Joined: 16 Feb 2010
Reputation: 5
Post: #3
RE: Mod Documentation/Manual Content & Format
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". Big Grin 2
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.
31.05.2011 16:36:05
Find all posts by this user Quote this message in a reply
Post Reply 




User(s) browsing this thread: 1 Guest(s)