That bit about using the documentation search is brilliant! That sort of initiative sounds exactly like what I’m talking about. Was it generalized to be used by all tools, or was it proprietary to a couple tools?

There was this documentation layer that basically acted as a broker between the UI displaying that data to the user, and a documentation store that lived in the tree. The manifestation of the documentation could be in whatever form you wanted, but I went for tooltips.

So if a user hovered over a piece of UI it would popup a tooltip describing what that piece of data did. The tooltip could also potentially contain a link that could be used to direct the user to further more verbose documentation. For example there are some pieces of data that are simple, but their use patterns are complex. In those cases the link could take the user to a page with images, tutorials etc describing the piece of data and how to use it in great detail.

The other cool thing was the tooltip also contained a link that invited the user to edit the documentation. This was useful for two major cases. The first is when a piece of data hasn’t been documented, the link could be clicked on and new documentation could be authored for that piece of data. The second is when the documentation was wrong or confusing. In these cases more power type users would be able to easily edit the documentation and fix the problems in context.

Also because the UI knows how to find its documentation the reverse was also possible. I wrote a documentation search feature whereby a user could search for something, and the search results would guide the user to the appropriate piece of UI. So if you know you need to add some in game IK to your animation for example, a quick search of “IK” using the tool would quickly show you where in the tool you need to setup that data. So users could focus more on knowing the strengths of the system instead of learning how to use the UI.

By minimizing the distance between editing documentation and consuming documentation, it was easier to make it work.

Anyway, interesting post. I look forward to knowing more about what you’re doing.