"Cosmic Droplet's" Plunge: Treating Tutorials Like Documentation

The Double Life of a Tutorial: Teaching Players and Yourself

Let’s face it, tutorials are a pain.

They take time away from core development, often feel repetitive, and are usually the first thing players skip.

But what if I told you that your tutorials could also be invaluable documentation for your game, constantly evolving alongside your code?

This isn’t some pipe dream. It’s about shifting your perspective on tutorials.

Stop Treating Tutorials Like Afterthoughts

Too many indie developers see tutorials as a necessary evil, a box to check off before release.

The result?

Rushed, incomplete, and quickly outdated tutorials that frustrate players and offer zero long-term value.

We can do better.

Think of your tutorial as a living document, a functional specification of key game mechanics.

It’s a way to teach new players, but also to remind yourself of how things actually work as the game evolves.

Consider this: if your tutorial breaks, it highlights a core mechanic change.

That’s invaluable.

Modular Tutorial Design: Building Blocks for Knowledge

The key to a documentation-friendly tutorial is modularity.

Break down complex mechanics into smaller, self-contained steps.

Each step should focus on a single, understandable concept.

This makes the tutorial easier to follow for players and simpler to update as your game changes.

In “Cosmic Droplet,” we initially had a single, long tutorial level that covered everything from movement to shooting.

It was a nightmare to maintain.

When we reworked it into smaller, distinct levels, each focusing on a specific mechanic, it became both easier for players to grasp the concepts and much simpler for us to update when we tweaked the shooting system.

Modularity allows you to isolate and address issues without rewriting entire sections.

Commenting With Purpose: Tutorial-Driven Documentation

Your code comments within tutorial scripts should explain why something is happening, not just what is happening.

This is crucial for both learning and documentation.

Imagine a tutorial step that teaches the player to collect a power-up.

Instead of simply commenting:

// Increase player score

Write something like:

// Increase player score - This gives the player positive feedback and encourages exploration.

The second comment explains the rationale behind the code, providing context for future developers (including yourself).

These comments can also be used to automatically generate documentation later using tools like Doxygen or Sphinx.

Updating Is Inevitable: Embrace the Change

Games are constantly evolving, so your tutorials need to evolve with them.

Don’t wait until the end of development to update your tutorials.

Incorporate tutorial updates into your regular development workflow.

Whenever you change a core mechanic, immediately update the relevant tutorial steps.

This prevents the tutorial from becoming outdated and ensures that it accurately reflects the current state of the game.

This requires discipline, but it saves time in the long run.

It’s far easier to update a small, modular tutorial step than to rewrite an entire tutorial from scratch.

Case Study: The “Cosmic Droplet” Experience

Let’s look at some specific examples from “Cosmic Droplet.”

Initially, our tutorial on enemy AI was a disaster.

It was a single, monolithic level that explained everything from enemy spawning to pathfinding and attack patterns.

As we iterated on the enemy AI, the tutorial quickly became outdated.

Updating it was a huge time sink, and it often introduced new bugs.

We decided to rework the tutorial into a series of smaller levels, each focusing on a specific aspect of the AI.

One level taught the player about enemy spawning patterns.

Another level taught them about enemy pathfinding.

And a third level taught them about enemy attack patterns.

This modular approach made the tutorial much easier to maintain and update.

When we changed the enemy attack patterns, we only had to update the attack pattern tutorial level, not the entire tutorial.

However, in contrast, our tutorial on using the “warp” ability was initially well-structured, but poorly commented.

We focused on explaining what the code did, not why it did it.

As a result, when we came back to update the tutorial, we had to spend a lot of time reverse-engineering our own code.

This experience taught us the importance of writing meaningful comments that explain the rationale behind the code.

Common Mistakes and How to Avoid Them

Here are some common mistakes indie developers make when creating tutorials and how to avoid them:

• Treating tutorials as an afterthought: Make tutorial creation a part of your core development process.
• Creating monolithic tutorials: Break down complex mechanics into smaller, modular steps.
• Writing vague comments: Explain why the code is doing something, not just what it is doing.
• Failing to update tutorials: Incorporate tutorial updates into your regular development workflow.
• Ignoring player feedback: Pay attention to player feedback on your tutorials and use it to improve them.

Your Tutorial: More Than Just a Learning Tool

By treating tutorials as living documentation, you can save time, improve maintainability, and provide a better learning experience for your players.

It’s a win-win situation.

So, the next time you’re working on a tutorial, remember that you’re not just teaching players how to play your game.

You’re also documenting your game for yourself and for future developers.

Embrace the double life of a tutorial, and you’ll reap the benefits for years to come.