Collaborative Documentation Or: How I Learned To Stop Worrying And Love The Google Docs

I love writing. I love both technical writing and creative writing. I think I love documentation because I'm not inventing a plot or story. I'm trying to describe and persuade, something I'm generally better at.

Feedback on my documentation has been consistent since graduate school where I seemed to have a knack not just for game design but for documenting game design. Something about my brain likes working out how a piece of software will work and interface with a player/user and describe it to others. Whether it's the developers, artists, and QA working on it, the leadership to approve it, marketing to sell it, or anyone else who needs to visualize what this thing that doesn't exist will be.

However, documentation for a project is rarely a solo endeavor. Be it a game design document or a product requirements document, even if only one person is writing, others have to weigh in on the contents and then reference back to it when implementing. And because of this, you can't just work on your own private little file and then email it out when it's done.

In this article, I describe wikis, my graduate research into using them for game design documents, documentation features of templates and transclusion, and compare the usage of a wiki to a Google Doc for collaborative documentation and internal company information references.

Spoiler: While I heap praise on Google Docs for individual documents, I continue to support the use of wikis for larger initiatives.

What is a Wiki?

Wikis are websites that serve as collections of knowledge that can be easily edited by the readers.

A wiki is a website that allows for collaborative editing. The need to be easily edited, that is not going through a third-party program like a CMS or uploaded from somewhere else is vital. The word wiki is Hawaiian for "quick."

The most famous wiki is Wikipedia which runs a technology known as MediaWiki. In the early 2000s, MediaWiki was also popularly used by various wikis for video games and TV shows. A sweeping MMO like World of Warcraft or Guild Wars would use it to chronicle the game, being filled with tips, how-tos, and insights on the game. As a total nerd, this is where I got into using wikis myself. To this day, most fan wikis for games, TV, and films are running on MediaWiki.

Most companies nowadays are using some kind of documentation solution that is effectively a wiki. Among them are Confluence, Notion, SharePoint, Aha!, ClickUp... there are many. Most of these trade the power and flexibility of MediaWiki for more built-in features, easier editing, project management functionality, and more integration with other tools like Slack or Jira.

A Game Design Document (GDD) is similar to a Product Requirements Document (PRD) in that it spells out the hows and whys of what the piece of software will be. It includes content, screen flows, wireframes, business logic, art direction, story, and more. Depending on the side of the game, a GDD can be quite long and involved.

Recognizing This Need as a Student

When I was in graduate school, much of the work was group work. This made sense as games, like most modern software, are developed by a multi-functional team. I was at the height of my Wiki editing, having recently wound down as a bureaucrat (the highest level admin on a MediaWiki) on GuildWiki where I got extremely comfortable with MediaWiki.

I noticed right away that we needed to improve how we worked together on game design documentation. Passing a Word document around was simply not sustainable. We needed something designed for collaborative editing.

These kinds of tools were still in their infancy for software development. Notion wouldn't be released until 2016 Confluence had come out in 2004 but I didn't personally use it until 2011 when I was constantly frustrated by its lack of features I needed. TikiWiki had come out in 2002; I'd used it for a summer job but wasn't impressed.

I could see the features I wanted:

• Version control. No more manual change log at the top of the document
• Multiple editors tracked by contribution
• The ability to templatize content
• The ability to transclude content from one part of the wiki to another.

For my independent study, I developed "HeatherWiki", which was a system of organization and a few custom mods that would demonstrate how MediaWiki could be used for collaborative game design documentation. I didn't think deeply about the name.

HeatherWiki allowed each section of the document to exist as its own page allowing for easier editing of single sections at a time, confined discussions to relevant areas, and easy reorganizing of the document. It allowed us to take advantage of the features of MediaWiki while bringing it all together into a singular large document. During my time at RIT, HeatherWiki was used by myself, my teammates, and even undergrads on their projects to construct their GDDs.

Retiring HeatherWiki

HeatherWiki relied on a 3rd party extension which I had then further customized. After I graduated, when that extension fell out of date, I found myself without the time or energy to resolve, and possibly rebuild it.

But more importantly, I was seeing how collaborative editing technology was advancing. My next job used Confluence because it was part of the Atlassian suite and we used Jira. My next job was a Microsoft house and using SharePoint.

I lost much of HeatherWiki over the years migrating webhosting and not having the bandwidth to keep it up-to-date especially as one of the core mods I relied on was also no longer being maintained by its creator. Today, the original wikis don't exist.

However, I remain proud of my prescience in seeing the need for wikis to be used in corporate spaces and especially the need for collaboration in documentation. (This was not a part of the process that was being emphasized when I was in school.) Software is rarely developed by a single individual: it is a team effort and a team needs a source of truth to work on. Like the software, the documentation itself needs the ability to be reviewed, edited, updated, and handled by multiple contributors.

Wikis to Google Docs Transition

I've used a variety of wikis over the years. Rarely have I been involved in selecting which one a team uses. When I moved to work at a small agency, Dopamine, I eventually moved to using Google Docs almost exclusively. Dopamine was building a game that did need documentation, but over time much of the work was strategy documents, pitches, and research for clients. It was there that I fell in love with Google Docs and began to reconsider my feelings about wikis.

Because Google Docs were easy to share on a per-document basis, easy to access, and easy to iterate on with others, they became one of my favorite tools as a documentation dork.

Nowadays I do almost all my documentation in Google Docs whenever I can. It has some very valuable features for collaborative editing:

• Free to use
• Automatically everything in the cloud
• Easy access control for view/comments/edit
• Supports suggestion mode
• Supports comments with in-line highlighting and threaded conversations
• Shows where others are in the document
• Supports version control
• Automatically creates a ToC (Table of Contents)/Document navigation if you use headers
• Easy to link to a section header
• Real-time editing
• Type docs.new in the Chrome browser, it will open a new document for you. (This works for sheets and slides too.)

Comments and comment threading in particular was something that few wikis supported as well as Google Docs did. This was an invaluable tool for asynchronous review and feedback on documents. MediaWiki and a few others supported commentary but it was either below or on a separate page from the content.

Many of these features were available in Word but Word was still evolving its cloud and simultaneous editing functionality. Word is also not free. At this point, it's been about a decade since I've bothered using it so I can't comment on how it compares to Google Docs.

Google Docs vs a Wiki

Real-Time Editing (Google Doc) vs Edit-Then-Save Editing (Wiki)

Google Docs supports editing and saving in real-time. Each change is stored instantly on the live version of the document as you work. This is great for things like making updates during a meeting with a team. It makes it less likely that you're edits will conflict with someone else's edits requiring a merge. This style of editing has no difference between the edit view and the live view.

However, it also makes the version control less granular. The versions are usually saved once or twice a day depending on edit timing. Because it is edited in real-time, users might find themselves deleting and typing over each other as they work. This tends to require a conversation in a second channel to resolve.

By contrast, even though wikis have advanced in the last decade with most supporting WYSIWYG editors (see also: #FeatureFriday 16 on markup and WYSIWYG editing), what you're editing is merely a draft. You make your changes to the draft and when you're done it is saved. Different wikis handle conflicts in different ways but, much like code merges, they don't necessarily need a conversation to resolve.

This is useful for finer version control as each save is its own version. It means that the document isn't sitting in a partially completed state as you're working on your edits. In MediaWiki, saves also support notes of what the changes were.

Navigation

Google Docs doesn't really have a means of navigating between multiple documents or organizing them in a way that users can explore them. Documents are stored on Google Drive and presented as a file system with folders. To find things, I generally rely on my browser history or the exquisite search functionality (it is Google after all). But if I was a new employee it would be a lot of clicking around to figure out what was where with no means of presenting information in more than one place at a time or categorization/tagging functionality.

There are no nav bars or central hubs. A user could manually create such a page and hope others will find it or send around a lengthy link to it. But it's not how it's meant to be used. It would be a separate document or have to be added to multiple documents not side-by-side with content like a navigation bar or categories. Additionally, linking between documents isn't as streamlined as it is on some wikis.

Transclusion

Transclusion is when one document presents content from another document inside of it. This allows there to be a single source of truth for a piece of content and for parts of content to appear in more than one location.

I ran into a desired usage just last night at a planning meeting for the Denville LGBTQ+ Alliance : We have monthly planning meetings where a significant discussion includes upcoming initiatives. During those meetings, I take notes on what was discussed, so it's available for folks who couldn't attend. I also set new action items for the org. At the same time, a large part of the conversation is updated on the progress of our upcoming initiatives including their own action items. This has me going back and forth between the meeting notes and the initiatives tracker. A better option would be to transclude sections of our initiatives tracker into the notes for each meeting allowing the data to be stored in a single location but easily viewed and from both.

Our team is spinning up a Notion instance to see if it will meet more of our needs as we continue to build out a body of content from businesses in town we'd like to work with, events we want to participate in, and holidays we want to observe.

A usage I hope to find is the ability to transclude a Google doc into my wiki. The Google Docs are better for preparing a formatted piece of material for print/distribution such as a one-sheet but you'd still want the contents to be visible on the wiki if possible.

Templates

Templates are chunks of content with pre-defined fields and formats. MediaWiki's powerful template structure was something I desperately missed upon switching to Confluence back in 2011. Nowadays, it's more common.

MediaWiki's template structure is expressed in Wikitext markup making it immensely powerful for those comfortable with the markup who understand how to pass template parameters around. When displaying template content, MediaWiki will insert templates very similarly to how it uses transclusion.

I used advanced template features at HIMYM Wiki combined with transclusion to locate all the information about an episode of the series in a single location. That data could then be read and displayed in different formats depending on template parameters that were passed. The result was that putting an episode name alone in the template brackets would print out the name of the episode, italicized, as a link to the page for the episode. This link even had a mouseover that would include a one-line summary of the episode and the episode number. The CSS and the content that supported that were transcluded from the templates to the page where they were being presented.

The same data was used to create info-boxes on the episode pages, entries for lists of episodes in a season, an info-box on the site landing page about the latest episode that had aired, and a few other places where you might want data related to an episode.

The principles of encapsulation, inheritance, and polymorphism from object-oriented programming were part of this process and my preference for both templatization and transclusion. Much as you don't want variables and methods doing similar things in different places in your code, you don't want elements of your documentation to exist in multiple places. It's imperative when building software, that the whole team is working from a single source of truth.

Google Docs comes with templates for various types of documents and they've recently added a feature called Smart Chips which has some similarities to a template.

A New Feature

I'm not obligated to include a new feature design in every iteration of my newsletter. The name has a dual meaning allowing me to simply feature my work. But I considered of one anyway while I was writing this: transclusion in Google Docs.

As usual, my feature ideas are not constrained by the limitations of ROI. In truth, this would almost certainly not be something Google would build. There's little to no demand. It would be difficult to explain to a user who isn't familiar with the concept. And it could be complicated to implement. However, the user experience of adding a transclusion seems simple enough:

Right-click ?add transclusion? find the document you want to reference ? find the section you want to be transcluded.

Interestingly enough, Google Docs does support transclusion from a "linked table" allowing you to insert a table from a spreadsheet and, when you make changes, it will show the updates in your doc. And Google Slides supports transcluding slides from other decks. This means the user experiences around editing transcluded comments have already been considered.

At the end of the day, transclusion is something I rarely miss. I can almost always replace it with a link and I do liberally.

Conclusion

I went from advocating for the use of wikis for a design document (or PRD) to a lover of Google Docs. I do almost everything in there. However, it isn't all-powerful. There are times when it makes sense to use a wiki still.

For an information repository that's easily edited, a wiki is a vital tool for almost any company. It is meant to be easy to explore, easy to edit, and ideally can transclude and templatize the content.

For a singular piece of documentation, that you're collaborating on, a Google Document is a powerful tool. Google Docs are edited in real-time. They're easier to share, easier to converse on, and easier for a small group.

Heather Arbiter is a Product Manager and Games/Gamification Designer. HeatherWiki was created as an independent study while pursuing her Masters in Game Design & Development from Rochester Institute of Technology . Heather was an admin at the original GuildWiki and How I Met Your Mother Wiki.

(Heather chose HIMYM wiki because the show had a lot of lore and the wiki for it didn't have much love. It was a perfect playground for combining information architecture techniques she'd observed at various wikis and her own opinions of how to present a television show to a fandom audience. Though Heather does love a good sitcom, HIMYM is far from a favorite today.)

#FeatureFriday is a biweekly newsletter about the intersection of product, gamification, and behavior written with a personal touch. This is the 24th edition of the series.