The Explanation LabAll 20 lessons

15 STRUCTURE · Information shaped like the task

Make the goal the menu.

You will learn how to organize documentation around what readers want to do, with concepts and reference one click away. It takes 4 minutes.

TASK See the problem in 30 seconds

The clip starts with API docs sorted by system parts, then breaks them into pieces and re-sorts them by goal. Watch where the pieces land.

26 seconds · lesson 15 of 20 from the full video

Back to the menu

CONCEPT Why goal-first docs work

THE NAME FOR IT

ISO/IEC/IEEE 26514 Information for users

ISO/IEC/IEEE 26514 · Design and development of information for users

Software documentation should lead with the tasks users want to do, and link out to concepts and reference.

People don't open documentation to learn how a system is built. They open it with a goal: sign in, get a token, fix an error. If the docs are sorted by system parts, every reader has to translate their goal into your architecture before they can start.

Sorting by goal moves that translation into the docs. Each piece of content gets a type:

Concepts and reference still matter. They just aren't the front door.

Back to the menu

TASK See a before and after

EXAMPLE DOCS · BEFORE

DOCS

  • Authentication Architecture
  • Token Objects
  • Session Management
  • OAuth Flows
  • Error Codes
  • Rate Limiting

Organized the way the system is built. Your goal is "call the API." Which one do you open first?

EXAMPLE DOCS · AFTER

WHAT DO YOU WANT TO DO?

  1. Sign inTASK Sign-in endpoint
  2. Get a tokenTASK Request a token
  3. Use itTASK Send the token in a header
  4. Refresh itTASK Refresh flow
  5. Fix errorsTASK Fix an expired token REFERENCE 401 vs 403 TASK Handle 429 responses

Same content, broken into pieces and sorted by the user's goal. Concepts and reference hang off the tasks that need them.

Here's one task topic from the new menu. It's short, it starts from what you already have, and it links out instead of explaining everything inline.

EXAMPLE DOCS · ONE TASK TOPIC

TASK Refresh a token

Before you start: you have a refresh token from Get a token.

  1. Send this request:
    POST /oauth/token
grant_type=refresh_token
refresh_token=<your refresh token>
  2. Use the new access token in your requests.

Result: requests work again.

CONCEPTS AND REFERENCE: Concept: Session lifetime · Reference: Error codes

TAKEAWAY

People arrive with a goal.
Make the goal the menu.

Back to the menu

TASK Reorganize your own docs

  1. List the top five goals readers arrive with. Use support tickets and search logs, not your table of contents.
  2. Break your existing pages into pieces. Label each piece task, concept or reference.
  3. Make one task topic per goal. Give each one steps and a result.
  4. Link the concept and reference pieces from inside the tasks that need them.
  5. Make the task list your docs' front page.

Back to the menu

TASK Have your agent do it

PROMPT
Reorganize the documentation below around user goals, following ISO/IEC/IEEE 26514.
1. List the 3 to 7 goals a reader most likely arrives with, in the reader's words.
2. Split the content into pieces and label each one TASK, CONCEPT or REFERENCE.
3. Write one task topic per goal: prerequisites, numbered steps, the expected result.
4. Under each task, link the concept and reference pieces it depends on. Don't paste them inline.
5. Output a front page that is just the list of goals.

Documentation:
[paste here]

What good output looks like: a short goal menu as the front page, task topics with steps and results, and concept and reference pieces linked rather than repeated.

Back to the menu

Sources