The impact of UX and the need for documentation

Evaluating Grey's argument and changes in the profession

UIs get simpler, code gets more complex

Natural language interfaces -- like an iceberg underneath

Moving into hyperspecialization

Just as people in the early days of industrialization saw single jobs (such as a pin maker’s) transformed into many jobs (Adam Smith observed 18 separate steps in a pin factory), we will now see knowledge-worker jobs — salesperson, secretary, engineer — atomize into complex networks of people all over the world performing highly specialized tasks.

— "The Big Idea: The Age of Hyperspecialization"

No UX designers to vet/filter poor designs in dev domain

TC jobs moving into developer domain

Developers are writing more docs due to specialized info

Write the Docs as Evidence that Developer Docs Is Growing

Shifts toward Markdown and docs-as-code

The current predicament for TC, and where the gaps are

Opportunities related to doc tools and processes

Incorporating structure into content

The aim [of structured writing] is not to eliminate complexity altogether – that is impossible – but to partition it so that each part of that complexity is handled by the person or process with the knowledge, skills, and resources to handle it.
— Mark Baker, Structured Writing: Rhetoric and Process

Tables don't work beyond 5-6 columns

Separate the content from the display

               media_specifications:
                 video:
                   h265:
                     ftvcube: Hardware accelerated up to 3840x2160p (4K) @ 60fps...
                     ftvgen3: Hardware accelerated up to 3840x2160p (4K) @ 60fps...
                     ftvgen2: Hardware accelerated up to 3840x2160p (4K) @ 30fps...
                     ftvgen1: Not supported
                     ftvstickgen2: Hardware accelerated up to 1080p @ 30fps...
                     ftvstickbasicedition: Hardware accelerated up to 1080p @ 30fps...
                     ftveditionelement: Hardware accelerated up to 3840x2160p (4K) @ 60fps...
                     ftveditiontoshiba4k: Hardware accelerated up to 3840x2160p (4K) @ 60fps...
                   h264:
                     ftvcube: Hardware accelerated up to 3840x2160p @ 30fps...
                     ftvgen3: Hardware accelerated up to 3840x2160p @ 30fps...
                     ftvgen2: Hardware accelerated up to 1080p @ 30fps...
                     ftvgen1: Hardware accelerated up to 1080p @ 30fps...
                     ftvstickgen2: Hardware accelerated up to 1080p @ 30fps...
                     ftvstickgen1: Hardware accelerated up to 1080p @ 30fps...
                     ftvstickbasicedition: Hardware accelerated up to 1080p @ 30fps...
                     ftveditionelement: Hardware accelerated up to 3840x2160p @ 60fps...
                     ftveditiontoshiba4k: Hardware accelerated up to 3840x2160p @ 30fps...
               ...
             

Display result

Identify the structure

               ElementName:
                 anchor: string
                 description: >
                   string
                 required: boolean
                 added: string
                 deprecated: string
                 parent_elements:
                   - name: string
                     deprecated: boolean
                 child_elements:
                   required:
                     - name: string
                       deprecated: boolean
                   optional:
                     - name: string
                       deprecated: boolean
                   this_element_only_required:
                     - name: string
                       deprecated: boolean
                   this_element_only_optional:
                     - name: string
                       deprecated: boolean
                 child_elements_notes: string
                 child_elements_this_element_only_notes: string
                 attributes:
                   - name: string
                     accepted_values:
                       - value: boolean
                         description: string
                         required: boolean
                 accepted_values: string (if empty, [])
                 example: |
                   code...
               

Display result

Using specifications with APIs

Swagger UI display from the OpenAPI specification

Identifying where the UX problems are

Surface problems to the right teams

So, how can we improve API documentation if the only people who can accomplish this task are too busy to do it...? One potential way [is to] reduce as much of the administrative overhead of documentation writing as possible, letting experts focus exclusively on the value-producing part of the task. ... a main challenge for evolving API documentation is identifying where a document needs to be updated. — Uddin and Robillard

Doc feedback buttons

Surveys at select milestone events

Summaries of weekly issues resolved

Leveraging information flow through docs

First we split complex process into chunks

Maps bring the pieces together

Complex systems contain feedback loops

Each new piece of data the user uncovers affects the path taken and the eventual outcome. … it does not lend itself to being performed with a defined set of tasks nor can those tasks be performed in a fixed order.
— Michael Albers, Content and Complexity

Sintering as an analogy

Systems developed independently but interact together

Specialization is required in order to understand more and more about the intricate systems around us.... But at the same time, the systems we are building ... are not only intricate and complicated, but also stitch together field after field.... The design of driverless cars is a good example, requiring collaboration among ... software, lasers, automotive engineering, digital mapping, and more. — Samuel Arbseon

Looking for fit across the docs, blogs, forums

Compress into smaller, more consumable units

Article summaries

Quick reference guides

Schema theory

By catering my design to meeting your experiences, I make these items easier for you to use in that context. — Kirk St. Amant

Four Components Model

Narrative paradigm

Structuring information around the customer journey

I came across a set of API resources for managing a DEG the other day. You could add, update, delete and get DEGs. You can also pull analytics, history, and other elements of a DEG. I spent about 10-15 minutes looking around their developer portal, documentation, and even Googling, but never could figure out what a DEG was. Nowhere in their documentation did they ever tell consumers what a DEG was, you just had to be in the know I guess. — Kin Lane

[Not] Recognizing familiar terms

Background knowledge sections

Docs as a "theory" to test

In a sense, many things on a software development project are theories, or more accurately, assertions that need to be evaluated. ... Just because some stakeholders ... say a requirement is valid does not mean that they are correct. We need to evaluate even the requirements to determine whether they define the right solution to the problem at hand. — Spence and Bitner

Upon initial publication, begin iterative cycles