Discussion Project and Package Documentation Workflow

As both a tech writer and development experience (DevX) engineer, I passionately believe that good documentation is foundational to UX and DevX alike, for internal and external users, developers, and general stakeholders. There's already plenty of useful documentation around DocFX itself - it's used by Microsoft, among others, to manage hundreds of thousands of pages of reference and conceptual documentation - but having Unity specific guidance, practices, and smoothed out DevX for getting our own package and project documentation published would be enormously beneficial.

I've been circling around the last couple days looking into how I can effectively document Unity packages and projects alike. The main distinction I make between them for this discussion is whether the documentation is meant to be published for others to build on or just exists to document the project itself for the team (regardless of whether those docs are public).

Of course, right now, a sufficiently motivated and knowledgeable person can use DocFX to document their own APIs and get a docs site up and running for their projects and packages, deciding for themselves whether that documentation should be publicly available.

Unfortunately, there's no easy or straightforward way to ensure that our documentation has effective cross references (xrefs) to the Unity APIs. Having xrefs is invaluable when working through documentation because it allows a reader to traverse the definitions and documentation for types without having to continually copy-paste names into a search engine. It makes for much easier reading and faster discovery. It also helps to drive traffic to upstream documentation and, if those sites have telemetry, enables them to get a view into who/what is driving that traffic, which documentarians (and PMs) often find useful for figuring out where to invest their limited resources.

Anyway, I went looking for a way to get a hold of xrefs for my documentation. I found this thread from 2018 inquiring about xrefmap.yml files for the Unity APIs, where a user suggested implementing a cross reference service, like Microsoft uses for the dotnet APIs.

I also found UnityXrefMaps and DocFxForUnity. The former, while useful, only builds the xrefs for the main docs, not experimental packages (I'm working on some DOTS stuff, so need those for xref) and is currently broken, though I'm investigating a patch. It has xrefs up to 2020.2 (see the gh-pages branch of the project for the list and to browse the YAML files). The latter is a fairly good UX but is hampered by the limited availability of xrefs.

In the DocFX documentation, there's this note:

DocFX supports reading cross reference map from a local file or a web location. It's recommended to deploy xrefmap.yml to the website together with topic files so that others can directly use its url in docfx.json instead of downloading it to local.​

Having the xrefmap.yml files available as web URIs would also be enormously helpful even as a stopgap for the service not being implemented, which I definitely understand has some maintenance and development costs.

I also stumbled across the Package Manager Documentation Tools, which certainly seems pretty neat, though it does immediately warn:

This is an internal Unity tool and is not supported for external use.​

What I would like to discuss, maybe even figure out, is how we can maneuver towards practices and tools that support delightful documentation for ourselves and our users, players, and the broader community.

I think there's already a lot of good prior art out there in various conditions of maintenance and modernity and I'm happy to pitch in directly as well as provide feedback and insight from my perspective as a (currently full time) technical writer and (formerly full time, currently hobbyist/incidental) DevX engineer.

 

Hi!

I've been dealing with the same issues. While reading this, I felt like I had been stepping on almost all the same footsteps you did. I've been trying to fix NormandErwan's UnityXrefMaps project but DocFx keeps failing when building UnityCsReference projects; it says that System.Collections.Immutable can't be found.

I've found that some Unity packages have xrefmaps available by adding "xrefmap.yml" to their docs url. For example: https://docs.unity3d.com/Packages/com.unity.addressables@1.21/xrefmap.yml. But I have yet to find a way to get an xrefmap for recent UnityEngine/UnityEditor versions.

Were you ever able to fix the UnityXrefMaps project? Have you found any other alternatives?

Thanks!

 

Hi, an update. I was able to make NormandErwan's UnityXrefMaps project work. Turns out I had to upgrade DocFX to the latest version for some reason. I'm also modifying DocFX.json to use a newer dotnet api.