Writing technical documentation for production readiness

General / 03 February 2025

In this blog post, I’ll share my thoughts and expertise on the under appreciated yet crucial process of writing documentation within the industry. I’m referring to the broader implications of outsourcing assets and texturing pipelines, excluding the financial aspects since they’re not my area of expertise. This topic likely extends far beyond the scope of a single blog post, and I may delve deeper into it over time.

Objective of Documentation

Clear documentation is essential for internal teams, new members (including partners and outsourcing vendors), and project management. It serves as a comprehensive reference for project information and workflow, eliminating misunderstandings and inefficiencies that save time and money. No one wants a tool or system set up by someone who left the company without proper documentation, leaving them uncertain about its limitations, setup, and potential improvements.

The key to its success lies in regular updates. This ensures that outdated or obsolete information doesn’t accumulate, potentially leading to code rot. Documentation should be detailed enough to explain the main process but concise enough to be easily accessible when needed, such as onboarding a new developer or updating it.

Analysis

  • Ambiguity regarding the documentation’s intended purpose
  • Inconsistent terminology causes confusion
  • Repetitive information encourages skimming rather than thorough reading
  • Information scattered across various locations 
  • Is it sufficiently clear to non-native English speakers (depending on your team and your vendors)?

Iteration

The following points will undergo a continuous process of iteration and evaluation in collaboration with your collaborators and team members. The ever-changing landscape of tools, workflows, and tech needs us to keep adapting and improving our development process.

  • Thoroughly review all the documentation, following each documented step-by-step to ensure its accuracy and identify any missing information.
  • Conduct buddy checks to verify that everything makes sense from multiple perspectives.
  • Organize the content based on its complexity, considering that not all artists need or would be comfortable exploring more complex topics.
  • The information is available, but it is currently separated from the fundamental concepts.
  • Evaluate any workflow issues, blockers, or missing features in shared content, such as shaders or textures/material library.
  • Understand your target audience: Are you writing the documentation for a developer who is expected to have basic knowledge of a tool, software, or engine, or are you writing it for someone who has never used it before?

Lessons Learned

If I were to start fresh, I would improve the approach by adding more clear images, callouts, or even videos to reduce confusion, which is especially helpful for visual learners. Before starting the project, I would suggest creating a layout and showing a proof-of-concept for the potential setup. Furthermore, collaborating with different departments will help us delegate and coordinate specific documentation tasks.

Example

Texturing & Materials (Main Category)

---> Basic Workflow (Subcategory)

    -> Simple Material Blend Workflow

        -> Bespoke Texturing Workflow

    -> Advanced Workflow

        -> Height Blend Workflow

Conclusion

Be open to rewriting, re-editing, and redoing a substantial portion of the initially written documentation. Don’t be overly attached to what’s been written. With a well-designed revisioning system, you can always undo any changes or unintended problems. View this as an opportunity to reflect on your personal growth and improvements throughout the process.