Key to Success with Lumberyard - Documentation

Hello Lumbernauts!

For this month’s Dev Diary, I would like to introduce Mike Cronin, our Program Writer on the Documentation team! See below for his Dev Diary.

Hello Lumbernauts!

My name is Mike Cronin and I am a programmer writer with the Lumberyard Documentation team. My background is primarily in game and film pipeline development and production, with a couple of detours into visualization for financial markets, sports, and scientific research. I’ve been an artist, animator, technical director, and an engineer. Though I am relatively new to the Lumberyard team, I have been closely following Lumberyard’s development since its initial release.

My path to joining the Lumberyard team began three years and three jobs ago. I had transitioned out of game development into scientific visualization. The research teams I was working with had gigantic datasets that they wanted to visualize and interact with in real time. I was familiar with resource constraints having been a console game developer since the days of the first PlayStation, but nothing prepared me for trying to visualize 120 gigabyte astrophysics simulations on an iPad using a game engine.

Lumberyard was not the solution at that time. AWS was the solution. Once I discovered how easily I could use AWS to load massive data sets in a game engine and stream directly to any device, I was hooked. I started to look closely at Lumberyard and AWS services because cloud features and Twitch integration were becoming very important to me. My mind was racing with possibilities for games.

Trying to learn Lumberyard on my own proved to be difficult. Over the first few years, the team had written a huge documentation set, but the documentation could not keep pace with Lumberyard development. Topics went stale as features were rapidly removed, replaced, and added. I fully understand the challenges many of you have been through to learn Lumberyard. Some features were well-documented; some features had little to no documentation; important bits of connective tissue were missing; and the on-boarding story left a lot to be desired. If you managed to have success with Lumberyard outside of a team environment, I salute you.

As fortune would have it, I was looking for a new role at the very same time Lumberyard’s documentation team was being restructured. I’d like to say my intentions for switching out of production into documentation were altruistic. The truth is, I thought there was no better way to learn Lumberyard than to write documentation and be paid to do it. I was happy to join the team, excited to learn Lumberyard, and looked forward to making huge improvements to the documentation.

In the last year, I’ve learned writing documentation for a broad audience and a package as complex as Lumberyard is difficult. When you are writing documentation for a team in a studio, you have a shared lexicon and can make assumptions about what the audience knows and how they will use the feature you are documenting. Writing public technical documentation for a global audience of artists and engineers with diverse backgrounds and varied levels of experience offers a whole new set of challenges.

The first six months were a trial. I was trying to understand new Lumberyard features as I was writing about them, learning the tools and process we use for documentation, and learning how to write. In the struggle for clarity in documentation, I have spent hours carefully considering and researching issues such as whether bone or joint is a more common industry term. What about skeleton, rig, or armature? Are we importing assets into Lumberyard, or exporting assets from FBX? Engineers and artists have different perspectives on just about everything. What do we call a mesh that is visible in-game to differentiate it from a collision mesh? Is renderable even a word? Microsoft Word seems to think not. I’ve discovered many words game developers commonly use don’t actually exist in any English dictionary. (Ed: Wait until “pogchamp” enters Merriam-Webster in 2022.)

I’ve just crossed my first year anniversary with Lumberyard, as have most of the other members of the documentation team. It seems fitting to close out the year by reflecting on what we’ve been able to accomplish in year one and talk a little bit about what to expect from documentation in year two.

In our first year, we’ve been able to make some very significant improvements. The User Guide table of contents has been completely restructured, which makes it much easier to find features and related topics by browsing. Some high value pieces of documentation, such as FBX Settings, have been rewritten based on your feedback. We’ve created a new Welcome Guide full of useful information and basic tutorials to help you get started. One topic I am particularly proud of is How Amazon Lumberyard works. This topic was truly a team effort. It contains all the high level information you need to really understand Lumberyard and can open the door to discovery. The team has made a consistent and concerted effort to improve our Release Notes. We’ve improved our API reference and have begun rolling out new API User Guides. We’ve also documented a slew of new features, retired some stale topics, and filled a few gaps along the way.

Now we are in year two and hitting our stride. We are developing consistent formats for feature documentation. Later this year, when you land on a feature page, it will contain all the important reference information you need and link you to related tutorials. We are shifting focus to Day One, Week One, and Month One topics and tutorials that will get you up and running and using new features quickly based on where you are in your experience with Lumberyard. The table of contents is going through further refinement which will make it even easier to locate the tutorial and reference information you need. We’ve been auditing the documentation and retiring topics that are stale or otherwise don’t contain useful information. This effort to overhaul the documentation is going to stretch beyond this year, but our goal for year two to improve the front door experience, provide basic feature coverage, and eliminate information that is not current or would otherwise create confusion.

I’m very excited for the year ahead. We’ve created a solid foundation, and I’m looking forward to making significant improvements to our feature documentation and shifting focus to tutorials and more practical documentation. We’d love to hear your feedback. If you have specific documentation issues, please use the handy feedback links found at the top and the bottom of every documentation page. If you have requests or questions about features, the Lumberyard Discord and AWS Gametech forums are here to help. Your feedback and requests are very important to us, and we’d like to ensure we are providing the documentation and information that is most important and relevant to you.