Writing Help Files

At some point in life, there comes a time when we realize that we don’t know everything. For some people this is later in life, while some realize it early on. In most cases, people who have realized this will try to find some sort of tool or instruction that will help them figure out the solution to the problem that they are facing.

This is where your game’s help files will come in. If a user is having problems with something, it’s your help files that are going to keep them playing your game(and sane). But not everyone is all that good at writing help files. Here are some tips to help you make sure that your user documentation is easy to read and actually helpful:

  • Keep Entries Short

  • Have you ever asked someone a question and had them write you a paragraph in response when you really just wanted a yes/no answer? That’s where this rule comes in. Time is a limited commodity in today’s world, and people don’t want to waste their time reading through 6 pages of documentation for the command ‘mv -R /dirname’. They want to read a paragraph, MAYBE two if the command is really complicated. That’s it. Seriously.

  • Keep Pages Scannable

  • Make sure that you differntiate between entry/section titles and their content. Users will commonly scroll down a page and look for a title that jumps out at them and seems to be the solution to their problem; you should do your best to make sure the titles that jump out actually ARE the solution to their problem.

  • Search Functionality

  • If a user is REALLY stuck, or just lazy(both of which are entirely possible), they’ll probably try to search your site somehow. Instead of forcing the user to use their browser’s ‘find’ command to find mentions of something, give them a search box, clearly visible on every help page in a specific area. This will make it easy for them to find what they need, and less likely to go somewhere else when they get stuck. Also, make sure your search page is actually USEFUL when it returns results.

  • Tables of Contents

  • Even though differentiated headings make it easy to scan a document, having a table of contents at the top makes it even easier. A user having problems can quickly scan the list and see if anything matches what they’re looking for, and then click on the name of an entry to visit the entry’s actual information. If you don’t want to hard-code the table of contents yourself, try looking around – chances are you can find one or two Javascript Table of Contents generators – or even build your own, if you can’t find something that works for you.

  • Put all related entries on one page

  • If there are a myriad of issues a user can have with building things at their shipyards, have a “shipyards” page, with a table of contents and every entry regarding problems users could have with their shipyard. Having the table of contents link to areas on the actual page makes it easier for users to use and reuse the page; when they’re done reading they just scroll back up to the table of contents. It also means that you need to load pages less, which will help to reduce server load if you’re optimized correctly.

At the end of the day, while we hope users will never have to see our help files, they’re still something where you can make huge gains in user retention, by just putting the effort in to make them nice to use. Why wouldn’t you, for such an easy way to keep users playing your game?

Wish there was more?

I'm considering writing an ebook - click here.


Luke is the primary editor of Building Browsergames, and has written a large portion of the articles that you read here. He generally has no idea what to say when asked to write about himself in the third person.

Wednesday, May 28th, 2008 design, help
blog comments powered by Disqus


Building Browsergames is a blog about browsergames(also known as PBBG's). It's geared towards the beginner to intermediate developer who has an interest in building their own browsergame.


Got Something to Say?

Send an e-mail to luke@buildingbrowsergames.com, or get in touch through Twitter at http://twitter.com/bbrowsergames