Skip to main content

6 posts tagged with "docs"

View All Tags

· 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.

· 4 min read
zach wick

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.


Chen, I. (2005). Behaviorism. In Encyclopedia of Distance Learning (pp. 127-147). IGI Global. (

· 4 min read
zach wick

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.

· 5 min read
zach wick

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 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 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.

· 4 min read
zach wick

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.

· 3 min read
zach wick

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.