Blog of Rob Galanakis (@robgalanakis)

All About Documentation

There is a recent article on Gamasutra: Game Dev Collaboration: Google Docs Style. Every developer has his own story about the failures of documentation. I would have hoped that those thinking about this the most have already moved past the ‘silver bullet’ naiveté Chris shows in that article (well, what do you expect from producers…), but apparently not. Which is sad, because the problem is a single concept with really only two solutions.

The problem is usability.

The solutions are resignation or intense investment.

No one wants to document because 1) It is a pain to document using any software or system, including Google Docs, and 2) It is even more painful to update documentation using any software or system, including Google Docs. When a virtual process is painful, there are always things we can do to make it less painful (and ideally, painless). Blah blah blah. The problem is obvious. The solutions are not.

Solution 1: Resignation. Don’t even attempt to document.

Obviously that is a bit of a generalization. Really, it means don’t force, standardize, or expect documentation. People will document things on their own, using the best ways available, when it becomes an obvious benefit. Ultimately, people are just asking each other for information, and remember that developers, like all humans, are incredibly lazy. How many times have you not bookmarked a document link someone sent you? How many times have you kept open an IM window because you don’t want to write the info down? This is natural. We are usually asking for help because we’re doing something unusual, outside of our day-to-day, and the truth is we don’t need this info that often. Documentation is not that useful when someone is learning something for the first time. It is more effective to learn from someone and the benefit of documentation is slight, especially when the documentation is not kept up to date.

All the wiki-cloud-collaborative-meta-web-editor software in the world isn’t going to change these facts. There is a barrier that even Google Docs, which I think is the easiest-to-use software for documentation available, cannot itself overcome.

So, like I was saying, doing nothing is probably fine, even for large projects. On small projects, communication is better. On large projects, things move much faster than the few foolhardy souls who are willing to document can keep up with. Things will get documented occasionally, and everyone will expect the inevitable, and who knows, maybe we’ll build our schedules to take this into account and we’ll build more intuitive systems, tools, and interfaces.

The one exception to this is for outsourcing, which I’ll touch on later, because the logic for an internal development team is inverted with outsourcers.

Solutions 2: Intense investment. Smart people make a serious effort.

The problem with documentation is that the systems for managing it haven’t achieved a high enough level of usability. The cause of that problem is, our best and brightest haven’t really worked on the problem. It doesn’t get respect. Which is strange, when you consider what we have figured out. We in games deal with a product that thrives on and is reliant on usability, and no one I know of, even those studios with awesome tools, have figured out documentation.

I don’t have an actual solution. I am working on one, and hopefully can implement it at BioWare, but it is just one possible solution and who knows if it’ll work. My point is that we don’t take it seriously. We don’t even think about it correctly. We treat it as a separate entity, but that treatment has failed us. It is a subset of tool design, the same way UI and menu design is. If you haven’t thought about documentation as a living component of your tool, your tool has poor usability, no matter how actually usable your application is. This ‘integrated documentation’ thinking is common in shrink-wrapped applications; just think of context-sensitive ‘F1’ that brings up help to the current word under the cursor in a code editor, or activity or menu generally. The added complexity in our industry comes with the fact that our tools and systems are constantly evolving and changing, and docs are almost always written and updated in spare unscheduled time by development team members- two complexities which generally do not exist for shrink-wrapped applications.

We need to start treating documentation as a first-class issue and component of our tools, no matter how bad our tools are. That doesn’t mean scheduling time, it doesn’t mean creating a documentation superstructure that sits on top of our actual tools, like wikis/google docs/word docs do. It means really, truly integrating documentation into design and implementation of tools, and having your best people work on the tech for it, and having all the documentation happen by the actual users (so hard-coded message boxes that display info are out).

Hopefully in a few weeks I should have some progress to show on my collaborative documentation framework, to back up what I’m talking about.

Addendum 1: Outsourcers
If you are deploying systems to outsourcers, there need to be changes to the above. Outsourcers should not be given tools in such a state of flux, period. If you can’t lock something down, you are doing outsourcing wrong, or you shouldn’t be outsourcing it. Once it is locked down, go ahead and document it, and it is the job of the developers who manage the outsourcers to keep the documentation up to date and to roll out changes.

Addendum 2: Wikis
Hailed years back as the answer to documentation problems, wikis haven’t worked (and I’m sure we’ll see the same with Google Docs if we continue the current trend). The reason is primarily (IMO) that Wikis use a system of organization completely different than a Word document. It is non-hierarchical, non-procedural, and has no organization. It makes a Wiki wonderfully suited to describe things (it works great as an encyclopedia), but terrible at documenting processes. A proper wiki has lots of cross references and modular information. How useful is this to document workflows? I’d say it is counterproductive, as I know I’ve been enticed to spend an entire afternoon adding dozens of pages to a wiki that ultimately actually give too much information for the user and are hard to follow. So all you’re left with on most wikis is a bunch of pages that basically read like Word docs anyway (all slash commands in the game, what the different fields of Tool X mean), with a shittier text editor than Word and equally inconvenient way of accessing information. Which is why I’d prefer google docs- it does away with all the pretentious wiki bullshit and just gives you a bunch of actual documents, that are easier to collaborate on (in real time!).

4 thoughts on “All About Documentation

  1. Interesting post. So I did a heap of work on an internal tool last year that had some neat (at least as far as I thought) documentation features. Basically the tool was for manipulating our game asset description files – ie the files that describe what an asset is, and how it looks to the game engine.

    There was this documentation layer that basically acted as a broker between the UI displaying that data to the user, and a documentation store that lived in the tree. The manifestation of the documentation could be in whatever form you wanted, but I went for tooltips.

    So if a user hovered over a piece of UI it would popup a tooltip describing what that piece of data did. The tooltip could also potentially contain a link that could be used to direct the user to further more verbose documentation. For example there are some pieces of data that are simple, but their use patterns are complex. In those cases the link could take the user to a page with images, tutorials etc describing the piece of data and how to use it in great detail.

    The other cool thing was the tooltip also contained a link that invited the user to edit the documentation. This was useful for two major cases. The first is when a piece of data hasn’t been documented, the link could be clicked on and new documentation could be authored for that piece of data. The second is when the documentation was wrong or confusing. In these cases more power type users would be able to easily edit the documentation and fix the problems in context.

    Also because the UI knows how to find its documentation the reverse was also possible. I wrote a documentation search feature whereby a user could search for something, and the search results would guide the user to the appropriate piece of UI. So if you know you need to add some in game IK to your animation for example, a quick search of “IK” using the tool would quickly show you where in the tool you need to setup that data. So users could focus more on knowing the strengths of the system instead of learning how to use the UI.

    By minimizing the distance between editing documentation and consuming documentation, it was easier to make it work.

    Anyway, interesting post. I look forward to knowing more about what you’re doing.

    1. That bit about using the documentation search is brilliant! That sort of initiative sounds exactly like what I’m talking about. Was it generalized to be used by all tools, or was it proprietary to a couple tools?

  2. […] other. I mean, providing a system of documentation for hacks, workarounds, known issues, etc. And, it must be said, the workflow for this system of documentation needs to be problem-free and as easy to use as […]

  3. […] ago I made a post entitled “All About Documentation.”  In it, I discussed how in order to solve the documentation problem, we needed to either […]

Leave a Reply