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.
References
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.
Educational behaviors rooted in the theory of behaviorism, or at least the operant conditioning branch of it, are
regularly used in software product design decision-making processes. Product onboarding, as an educational experience,
is an archetypal application of these theories. For instance, within the sequence of informational popups that show a
new user how to use a piece of software, the button with the positive, forward-in-the-onboarding-process
call-to-action (such as "Next", or "Okay") should be consistently placed and styled, and match the styling of the rest
of the product. This has the result that a user is gently nudged towards learning the visual cues and language that the
product they are being educated on uses. As described by Chen, such reinforcement of the visual language used within the
software would positively influence the perception category of Bloom's psychomotor domain, which deals with "the
ability to use sensory cues to guide motor activity" (2005, p. 133).
The order in which new users are guided through the main features of the software product also influences the
educational impact of the onboarding. In Bloom's affective domain, which includes a learner motivation dimension among
others, the organization category "organizes values into priorities" (2005, p. 133). Because learner's motivation is
increased when learning a high priority item, the new user onboarding process should show the most important feature (or
features) first. This helps ensure that new users are able to not only see value in becoming revenue generating
customers of the software product, but that they are educated the most effectively on how the software can be used to
solve their business need.
Behaviorism is present in significant ways in many popular software based educational tools. For example, the online MBA
program offered by Bowling Green State University relies heavily on the Connect and SmartBook products from McGraw-Hill.
SmartBook is a web-based software product that uses programmed instruction as written of by Chen (2005). This
behaviorist style of instruction uses a series of sets of questions each associated with a section of reading. In order
to progress forward through the instruction, the learner must answer the set of questions correctly and may be required
to re-experience the associated reading if the questions are answered incorrectly multiple times. This type of
instruction is appropriate for the content of this program which is often centered around analyzing a financial process.
As described by Chen, behaviorist theories of learning position spaced repetition as an integral part of the learning
process (2005). The idea of using repetition to impact learning can be leveraged with consistent use of language cues in
software product documentation.
Consider the software documentation for a generic REST API for a todo list tool. Using this REST API, a user can create
new, read existing, update existing, or delete existing todo items for themselves. The documentation for such an API,
should start with the most important use case first, to influence the organization category of Bloom's
affective domain as discussed above. In our example, this means that the first bit of documentation should be how to
create a new todo list item.
In the language of REST APIs, a task to be done in our example is called a resource. When talking about the resource
in the documentation for this API, the capitalization and styling of the resource's name should be consistent and
visually distinct from other uses of that resource's name as a word. This means that when referring to the resource that
corresponds to a task to be done, it should be consistently referred to as "a Todo" with a capital letter as an English
proper noun.
In the contrived example of a todo list REST API, the benefits of this kind of repetition may not be evident. However,
consider the REST API for a payment processing product. In that context, many of the resources needed while moving
through a payment process are commonly used nouns and verbs in addition to being important foundational concepts of how
the software product works. A good example is the API resource of a Charge which is the software representation of
taking a payment from a customer. In the documentation around how to interact with a Charge API resource, there are
sentences that read similar to:
To charge a Customer, create a Charge object.
In this example documentation sentence, "charge" is used as the English verb while Charge is typographically
identified as being the API resource. In keeping with the behaviorist emphasis on repetition to influence learning,
being consistent in the typographic indications of what object or abstracted concept is being referred to allows readers
of the software documentation to have a positively impacted educational experience.
In robust engineering organizations, engineers contribute code to a shared work product through a process call pull
requests.
This process is facilitated by pieces of software such as git
, mercurial, and fossil, which enable version control of
software.
Using these software tools, along with a collaboration platform such at GitHub
or GitLab, engineers make proposed changes to the shared codebase which are then reviewed by peers
prior to applying these changes to the shared codebase. These changes are submitted as a pull request to the shared
codebase, and the review is often called a pull request review.
Because of their nature as an integral step in the work process of every engineer, regardless of their skills or
experience, treating the pull request process as an educational one can positively impact every engineer that works on a
particular codebase. When viewing the pull request process this way, it becomes clear that it has all of the necessary
characteristics of a
good assessment.
A good assessment must be objective and have a clearly defined outcome. When an engineer makes code changes that result
in a pull request, the changes were made with some goal in mind. That goal is sometimes the addition of a new product
feature, sometimes fixing a bug, or sometimes improving performance. In any case, there is an objective goal that the
code changes under review are intended to achieve. The peer charged with performing the pull request review similarly
has only three available actions. The reviewer can approve the changes with no feedback, approve the changes with
feedback, or reject the changes with feedback.
In the first case, the pull request as an assessment is of only limited value. Such a pull request only affirms that the
engineer's code changes met the intended goal. In the case of a pull request being approved or rejected with feedback,
the inclusion of feedback offers the reviewer the opportunity to provide formative or summative feedback. This has the
implication that effort put into providing quality feedback on pull requests has an impact on the quality
of future pull requests that take the feedback into consideration.
A good assessment must also be valid, in that it evaluates the actual skill under consideration. Within the context of
pull requests, this means that feedback and reviews must be limited in scope to the code changes under consideration. It
would be inappropriate for a pull request reviewer to reject a pull request because they didn't like that its creator
ate a particular food for lunch.
Using product features of Github,
namely pull request templates
, Checks, and automated test suites, pull requests can be more soundly formed
into an assessment tool.
Pull request templates enable code maintainers to provide a templated familiar set of content that engineers must
address and
follow in the process of creating their pull request. These templates often include directions to have the proposing
engineer explain in their own words what their code changes do, consider any follow-on effects, and provide any other
information that a reviewer would need to evaluate the code changes.
The GitHub Checks product feature enables code maintainers to programmatically enforce code conventions and provide
instruction to pull request creators that voilate them. This product offers the ability to provide formative feedback at
scale.
Automated test suites are of critical importance in any software product, but take on a new role as a means of
self-assessment when viewed through the lens of pull requests as an assessment tool. These automated tests run against
the modified code and ensure that the behavior is as expected.
Pull request reviews cannot replace targeted instruction. They can however augment previously given instruction and
scale its reach to a wide audience. When onboarding new engineers to a team or product, pull request reviews and the
feedback contained therein are the most impactful educational experiences related to the engineer's day-to-day job
functions. This importance should be honored by giving pull request reviews the respect that they deserve as a powerful
educational tool.
If grown organically, documentation experiences tend to be fragmented, inconsistent, and often don't clearly map to how
users can use the documented product offering to solve their own technical problems. These issues make the documentation
content more difficult to maintain and more difficult to add to in a self-consistent way.
Revamping the documentation experience with an eye towards improving the information architecture and thereby improving
the maintainability and extensibility of the documentation content is the best solution to these issues.
At the highest level, moving documentation into its own separate and distinct product from the documented product is an
integral initial step in this revamp process. During this migration, it is prudent to adapt the content to use the
appropriate content template based on the documentation type and adjust the information architecture of the navigation
to realign the documentation experience around solving user's business problems.
What should the infrastructure underlying the documentation experience be? How exactly should the documentation
experience be architected?
Building the documentation experience as its own product has the greatest amount of engineering cost, but provides the
most flexibility in what the resulting documentation experience can be. This option implies a separate maintenance
burden for the documentation apart from the documented product. The resulting documentation product from this option
could be released as a free and open source documentation framework that just so happens to have a particular instance
that documents a given product. However, this follow-on action also has the implicit resource requirements of any free
and open source project - namely maintenance and hosting costs.
Building off of a ready-made solution like TailwindUI's Syntax template would
be a one-time payment of ~$799 USD in most cases, and would preclude a free and open source product offering being made
from the built documentation experience. Alternatively, using a free and open source project
like Docusaurus enables building the desired documentation experience within a no-cost framework.
Alternatively, documentation experiences can be built using an off-the-shelf SAAS documentation solution
like readme.io.
This option provides the lowest ongoing maintenance burden, but requires an ongoing payment obligation to the SAAS
provider. This option allows documentation creators to focus their efforts on the content of the documentation
experience instead of having a split
focus on the content and the infrastructure. Using a documentation SAAS product also enables the easy collection of
documentation specific metrics that can be used to drive internal decisions. These metrics may be available under the
other options, but require an engineering effort to gather them. A "Business" license for ReadMe.io is typically around
$399 USD/month.
When a user enters a documentation experience, they presumably are attempting to solve a problem. The documentation
experience should expedite the search for a solution that features the documented product by aligning the entry into the
documentation experience with common user business problems. In addition, the design of the documentation experience
entry point should provide a quick overview of the available types of content and encourage visitors to explore of their
own curiosity.
Within many pieces of documentation, there are listed steps of more than one separate and distinct way of using a
product or feature. When all the documentation content is organized vertically, it is difficult to visually
identify where one set of steps ends and where another set begins. A tabbed interface provides a horizontal axis on
which to visually separate distinct product/feature usage experiences.
It is also important that the internal structure of documentation content is consistent. For each type of
documentation content, there should be a common base template with optional additional components. This helps ensure
consistency and helps lessen the maintenance burden of the documentation content. Such templates also provide a way to
scale a self-serve documentation creation model in which the documentation team acts more like an editorial agency or
collaborator instead of as the primary author because example content and helpful hints can be placed within the templates.
The four general types of documentation content are quickstarts, procedural docs, conceptual docs, and reference docs.
Quickstart documentation aims to help readers get up and running with the documented product quickly, and are usually
framed in terms of solving a particular specific business problem. These business problems are usually identical to the
main use cases of the documented product.
Procedural documentation is what is most often called "documentation". Procedural documentation is step-by-step guides
that educate a user on how to use the documented product to solve a particular problem. These are distinct from
quickstarts in that the goal of quickstarts is to quickly demonstrate the documented product's usefulness, while
procedural documentation is more focused on the eventual outcome instead of execution speed.
Conceptual documentation is intended to explain the concepts and ideas behind the documented product, without specific
implementation details. Conceptual documentation should describe how the documented product works, not how to use the
product.
Finally, reference documentation seeks to explain which exact product actions have which exact effects. These types of
documentation typically are an exhaustive listing and explanation of configuration options and product features.
Constructing a set of templates for each of these four types of documentation enables the documentation as a whole to
remain self-consistent while having a distinct medium by which to achieve each documentation type's specific goal.
Modern computers, or rather the computer programming languages that control them, are Turing-complete. This means that
computers as we understand and experience them today can solve any problem whose solution can be solved by an algorithm.
Because any two Turing-complete systems can simulate each other (this is called equivalence), there exists more than
one way to solve a given problem using a computer (or any other kind of Turing-complete system). This necessitates that
when learning how to use a computer to solve a problem, the human involved in that decision-making must use a
constructivist point-of-view to evaluate the computer-aided solution. That is to say, using a computer to solve a
problem is more like building a bridge out of local stone whose design is inspired by previous stone bridges that the
architect has experienced; it is not like uncovering a universal truth as in Michelangelo's description of revealing the
statue that was already within the block of stone:
“The sculpture is already complete within the marble block, before I start my work. It is already there, I just have
to chisel away the superfluous material.”
The educational process of learning computer programming, which is the same as learning how to evaluate if the
computer-aided solution to a problem is sufficiently correct or not, requires practice making similarly shaped
evaluations in a wide variety of contexts to develop a sense of what constitutes a faithful representation of the
problem to be solved and its proposed programming solution. This is similar to the idea of finding success by getting
lots of shots on goal. Phrased another way, educational experiences are best for the learners when tools and methods are
evaluated on a per-learner basis instead of just assuming that if a given educational experience works for one learner
then it will work for all learners.
To encourage learners to practice these skills in ways that grow in complexity proportionally to their skills and
experience, tools can be specifically selected that lend themselves nicely to this process. For example, there exists a
programming language called APL, which began as a set of handwritten notation to help learners express algorithmic
solutions to problems in an abstracted way. The notation of APL lends itself well to the mathematics of arrays, and
because of how exactly its notational language can be composed (via grammar rules as in any other language), APL also
serves as a powerful computer programming language. It is particularly well suited to the task of teaching computer
science concepts to new learners using the language of basic arithmetic and elementary array manipulations. In fact, APL
was created as an abstraction of the existing mathematical notation for these areas to facilitate exactly this
constructivist style of learning by applying existing knowledge from one field of study to a new field in order for
learning to occur.
When applied to documentation, the takeaway is to present the same content in a variety of ways to increase the
likelihood of a learner finding the documentation useful. The easy trap is to churn out a laundry list of
cookie-cutter-shaped retellings in different media formats - screencasts that are simply readings of blog posts, live
talks that are just live versions of the screencasts, and so on. Instead, take advantage of the unique features of each
medium to enhance the material. For screencast-shaped documentation, this means longform content that shows a worked
example of a real-world problem that a user can solve using the product. For live talks, real-time interactivity is the
main unique feature.
As always, the message of any communication must be tailored to its audience. However, the medium of the message acts as
the limiting reagent for the act of tailoring the message to its audience, and so to optimize for the impact of
documentation is to carefully choose the least limiting reagent for the intended audience.
That sentence might be a vague instruction coming down the chain-of-command to you. That sentence might something that
you aspire to do. In either case, that statement of "Write better docs." might be something that you’re actively working
to do. If you find yourself in this final group, then this text is for you.
You already know that the documentation that you create should be useful, but what does that mean in practice? Does it
mean that users can use your documentation to solve their implementation issues? Does documentation being useful mean
that your documentation helps users improve their business processes? Or does useful documentation only mean that its
existence is a positive value proposition by your sales counterparts?
Useful documentation can do all of these things and more.
Documentation is the force multiplier for marketing efforts when the product being marketed is a shovel or pick in a
gold rush. Good documentation can make a poorly marketed product sell decently and great documentation can augment great
marketing to best-in-class.
For businesses making software building blocks and selling them as these picks and shovels in the Big Tech/Silicon
Valley software-as-the-savior gold rush, best-in-class useful documentation rewards as both an economic return and as an
increase in the quality of the portion of the customer base that requires support.
Making useful documentation isn’t just getting rid of passive voice and putting in lots of screenshots. Making useful
documentation requires a full reframing of documentation as a product experience where the reader is taken on a
journey through the implementation and nuances of how your product applies to their scenario.
Documentation is usually treated as a hastily thrown together, constantly out-of-date content-island. Treating
documentation as an educational experience instead allows for the documentation experience to instill lasting
impressions in its participants. For readers of useful documentation, their personal educational motivations are
aligned with their immediate business needs and the spirit of the documentation. By teaching these participants how to
apply your product as the best possible solution to their particular business problem, your product's positive
associations with that user are increased and you have a perfect opportunity to educate them on the why of your
product's features. These active learners form an audience of highly motivated learners and are a captive audience for
marketing messages.
A user who understands why and how your product functions is educated on your product with declarative knowledge of what
your product is and procedural knowledge of how to use your product's features. Such knowledge transfer is the purpose
of the field of study of Instructional Design.
This means that if documentation experiences are treated as educational experiences, then they can be made more
impactful by analyzing them through the toolset and frameworks of the instructional design world.
