Opinion: Improving Your Documentation

[In this reprinted #altdevblogaday-opinion piece, PixoFactor's Adam Rademacher offers some general technical writing advice on how to improve your game documentation.] Game Design is about the merging of ideas and the creative evolution of complex entertainment software from idea through delivery. Nothing in this process is more important to the designer than effective communication and memory over long periods of time. Enter the role of documentation. Preface Trying to improve your documentation is a long and arduous process. Unfortunately, I don't know of any way to build these skills without practice and critique. If you have any friends who are editors or writers themselves, they can often give you good feedback — but be careful of those who work solely in creative writing. Technical writing is not creative writing, though they share some parts of their skill sets. So, I have to give you this advice: if you want to improve your technical writing, write more. What's The Point? Technical writing differs greatly from other forms of writing in its purpose, and it's important to recognize that purpose: communication. All writing is about communication, but technical writing begins with a clear understanding of the purpose of the document you are writing. Here are some examples:

Keep It On Track Keep the goal in mind the entire time you are writing the document. Information not relevant to the goal will only create noise, making it more difficult to understand. As you write, it will help you decide, "Does this information need to be here?" It is easy to litter your documentation with stray information that comes up while you write, but probably isn't that useful in terms of the document. On the same point, put things where they belong. If you have a section on Enemies, make sure it contains ALL of the relevant information on Enemies. Don't put your Enemy Statistics in one section and your Enemy Descriptions in another unless you really have to. Show, Don't Tell We are visual creatures, and like to communicate visually. If you're having difficulty describing something in your text because of its complex or abstract nature, sketch it out. Then put that sketch into the document. A little forethought into the presentation of your information can go a long way. Try to put any "listed" information into bullet points, or, even better, a chart. Prepare For questions Questions on your documentation are great. They lead to better understanding and clarity for all. When someone asks you a question about the documentation, however, be sure to add that information to the doc again later. Either that, or prepare to answer the same question over and over again. Make It interesting If your documentation is dry and unfeeling, no one will read it. Sure, they'll skim through it and get a feel for the gist of it, but they won't digest the information and understand it the way you do. Your game is going to have a personality, so try to inject that in your writing. But, don't let it get in the way of communicating the information. Communication is king. Grammar And Spelling Don't kid yourself. It was easy to blow this off in high school and even college using spell check on your essays, but now you're a professional, and you're writing to communicate. Spell check isn't as good as you think it is, so don't rely on it. Even one misused term can derail your reader significantly, so write like a professional. When in doubt, Document it! [This piece was reprinted from #AltDevBlogADay, a shared blog initiative started by @mike_acton devoted to giving game developers of all disciplines a place to motivate each other to write regularly about their personal game development passions.]