Documentation

Today

To begin considering improvements to documentation, we must first understand the purpose of documentation. If we were able to share knowledge with a mental link, we wouldn’t need to have a shared language of communication. This means that the purpose of documentation is to share ideas and guidance asynchronously.

A person with an interest in the system will visit documentation when they need to learn more about information related to the task they are working on. These tasks often vary based on the audience; a designer will commonly visit documentation to gain knowledge about a pattern and its options. A developer does not often need to know when to use a pattern, only how to replicate the result as code as instructed via a designer or their specification.1

This is why Storybook has been such an influential tool in the design systems practice. Its main objective is to visually present common patterns and expose further options in an accessible way. Both designers and developers need to know what’s available to them either for crafting or executing.

Video has been a popular method of providing education but for it to be effective, it should come with a text search. Otherwise, you could be wasting time watching or scrubbing through the media which ends up not being helpful. This is commonly the case for many design tutorials, where a designer might be looking for a single technique buried in a multistep procedure. Presentations can also lose interest with a mixed audience; some more knowledgeable folks may tune out during the foundational parts before introducing the new concepts.

Tomorrow

Artificial intelligence is beginning to play a part in the documentation. Requests from teams looking for answers that have difficulty wading in a sea of information would rather ask for quick results. Much of what we do is meant to react to a real-world production environment; every moment can count. Fewer moments searching for the answer allows for more crafting of the solution. However, AI isn’t trustworthy yet and its confidence can be misleading.

As a stepping-stone to this concept, we may consider a ”choose your adventure” documentation style; where a designer is presented with options related to the experience they are crafting. Each choice provides more insight into the best recommendation or recommendations. This combats Hick’s Law, as a list of components and patterns makes it the responsibility of the designer to not only know what every single resource is, but how to use it. This alternative wizard for documentation should provide better results by reducing the set of options and having a clear understanding of why these recommendations are offered. This is similar to Atlassian’s Design Token Picker but for patterns.

We should also be sensitive to designers visiting this sort of documentation often; as traveling through the wizard for each task would be time-consuming. There is an element of gamification that could exist here; where components and patterns “unlock” as you discover them or better yet, a proven competency in them. In this way, we can be sure that designers understand the purpose of any particular pattern instead of choosing it for the wrong reasons.

Case in point, inexperienced designers creating a profile page may consider using a date picker component for birthday entry with a misunderstanding that date pickers are used for all date input tasks. This is a suboptimal user experience; birthday input is better prepared using a combination of select and text input elements. The wizard could help direct this education; the following is a sample of questions:

  1. Is your experience interactive? (interactive)
  2. Does the user need to provide information or execute an action? (provide information)
  3. …(additional questions that focus towards date input)…
  4. Do we expect the incoming date to be relatively recent or farther away in time? (farther away)

Recommending a combination of select and text inputs for the following reasons…

There is also a possibility of a design assistant but reminiscent of “Clippy” from the Microsoft Office suite. In this way, the act of creating an interface could learn what is being built from clues and provide suggestions or instant replacements within the design tool. Historically, these sort of recommendations have been often annoying or uninformed but with advancements in technology and general acceptance to AI we could see more folks adopting this kind of workflow.

This previous idea is an important consideration; the goal is to not leave the tool we are working within. An example of this in development is VSCode’s GitHub Copilot where a developer can leverage/ the power of AI without leaving their IDE. This can increase productivity by reducing context switching between code and reference. There can be a world without traditional documentation; passively learning by doing.

Footnotes

  1. I’ve segregated the roles of designer and developer here to identify common responsibilities. It is also common for a single person to have both responsibilities and therefore represent both audiences simultaneously.