Skip to main content

Documentation experience philosophy

· 3 min read
zach wick

When working in the area of software developer enablement, my goal is to get the developer to be as effective as possible, as quickly as possible. For software businesses that serve technical audiences, product adoption is often predicated by educating potential customers on why your software product solves their issue. This is best done by providing a structured knowledge set that is efficiently consumable by the intended technical audience.

To do this requires having a complete definition of who the audience is, and then tailoring the educational experience to that audience. By aligning story based guides to common product usage patterns, the educational experience's goals and the learning developer's goals are aligned to enable more motivated learning (Ambrose, 2010, p. 73).

In order to provide a mental scaffolding of how the various product configuration options work in concert, all educational language must be consistent and particular in its use. For visual educational content, the particular words used and medium that they are presented in must be consistent. Typefaces and other visual cues can be used to impart special meanings to written content. This visual separation of language helps learners differentiate when they need to use declarative or procedural knowledge to complete their product use case. (Ambrose, 2010, p. 34).

In order to effectively reach learners of different styles, the educational experience must be broad in its means of publication. Some developers will be most efficiently served by having a comprehensive documentation set of every product configuration option. This publication strategy provides the informational organization for this knowledge to lower the cognitive burden of learning it (Ambrose, 2010). Other developers will be quickest to be successful by watching another developer use the product in a meaningful way. These developers are motivated by seeing real world applications of this technical product knowledge. Ambrose suggests that tying new knowledge to real world applications of that knowledge motivates some learners (2010, p. 83).

When product adoption is predicated on product education, then it is in a software companies' interest to ensure that its product education is as impactful as it can be. This educational experience can be maximized by motivating its technical audience to engage with the material and making the knowledge structured and easily consumed.


Ambrose, S. A., Bridges, M. W., DiPietro, M., Lovett, M. C., & Norman, M. K. (2010). How learning works: Seven research-based principles for smart teaching. John Wiley & Sons.