Choose Knowledge Formats Humans and Agents Can Use

You do not need one perfect file format for all your information.

You need a small number of formats with clear jobs.

Keep the approved original where people already work. Let Codex or Claude create simple working copies and useful reading views. Make sure everyone can tell which version is in charge.

Who this is for

This guide is for managers, founders and organisational leaders whose information is spread across documents, notes, spreadsheets and shared drives.

You do not need to understand file standards or write code. You need to decide who owns the information, which version governs a decision and what people need to do with it.

Before you start

You need:

• one harmless document you are authorised to use;
• its approved location in Drive, SharePoint or another company store;
• a local practice folder;
• Codex or Claude;
• and about 45 minutes.

Do not convert your whole company archive for this exercise.

What you will learn

By the end, you should be able to:

1. name the approved original;
2. choose a useful working format;
3. ask your agent to create a readable browser view;
4. keep owner, date and status visible;
5. use a diagram only when it clarifies a real relationship;
6. rebuild the generated views without damaging the original.

The simple model

The approved original remains in charge. Everything else should lead back to it.

This guide keeps the diagram as Mermaid plain text. Why Mermaid works for people and agents explains the choice.

Step 1: Name the job

Ask what the information must help someone do.

You do not need to choose the technical format yourself. Explain the job to Codex or Claude and ask it to recommend the smallest useful set.

Step 2: Keep the approved original where it belongs

If people approve work in SharePoint, Drive, Word or Google Docs, leave that approved process in place.

Ask your agent to work from a reviewed copy. Record:

• the original location;
• the owner;
• the source date;
• the date the copy was made;
• the approval status;
• and who may read it.

The working copy is useful. It does not quietly become the company record.

Step 3: Ask for a simple working page

Paste this:

The agent may suggest Markdown. That is simply a plain-text format with headings, lists and links. You can read it without specialist software.

Step 4: Add a structured record only when needed

Sometimes a system needs to recognise the same fields every time: owner, date, status, review date and source link.

The agent may suggest JSON. JSON is a strict format for small records that software can check. It is useful for consistency and unpleasant for long prose.

You do not need to write it. Ask:

Step 5: Ask for a browser view

HTML is the format browsers display. Ask the agent to generate it from the working page rather than maintaining a second version by hand.

Say:

If the working page changes, rebuild the browser view.

Step 6: Add a diagram only when it earns its place

A diagram should clarify a flow, decision, sequence or relationship.

Ask:

If it would help, require a written explanation beside it. The diagram is a view, not evidence. Important steps still need links to sources.

Why Mermaid works for people and agents

Mermaid stores a diagram as short plain text. A person can read and edit the steps, an agent can safely propose a change, and the same source can be rendered as a visual diagram.

That makes the diagram versionable, reviewable, portable and easier to maintain than an opaque image. You can see exactly what changed and rebuild the visual without redrawing it by hand.

Mermaid does not replace every visual. A photograph, detailed illustration or data-rich chart may need another format. Use Mermaid when the important thing is the flow, sequence, decision or relationship, and keep a written explanation for people who cannot use the visual.

Step 7: Make the important facts survive every format

Every important page or record should keep:

• title;
• owner;
• original location;
• source date;
• copy date;
• review date;
• status;
• audience;
• and related sources.

Use a small set of status words: draft, reviewed, superseded, disputed and unknown.

A page can sound polished and still be a draft. Make the status visible.

What the agent handles for you (optional)

Codex or Claude can:

• create Markdown, JSON and HTML;
• check that structured records are valid;
• create safe diagrams;
• compare a new page with the approved source;
• rebuild browser views;
• test links and headings;
• and explain any error in ordinary language.

Your job is to decide what the information means, who owns it and whether the result is ready to use.

Hands-on exercise: one document, three useful views

1. Choose one harmless approved document.
2. Keep it in its current governed location.
3. Ask the agent to make a local working page without changing the original.
4. Review the owner, dates, status, evidence and unknowns.
5. Ask for a browser view.
6. Ask whether a structured receipt or diagram is genuinely needed.
7. Open the browser view and follow its link back to the original.
8. Change one sentence in the working copy and ask the agent to rebuild.

The exercise is complete when the browser view updates and the original remains unchanged.

Verification checklist

• [ ] You can name the approved original.
• [ ] The working copy records its owner, dates and status.
• [ ] The original was not changed.
• [ ] The browser view links back to the original.
• [ ] A person can understand the page without knowing file formats.
• [ ] Any structured record contains only the fields a system needs.
• [ ] Any diagram adds information rather than decoration.
• [ ] The generated view can be deleted and rebuilt.
• [ ] The agent reported what it checked.

Common mistakes and safe recovery

If conversion goes wrong, preserve the approved original. Delete only the generated practice view, then ask the agent to rebuild it.

Ready-to-copy prompt

Do this now

1. Choose one harmless document.
2. Paste the ready-to-copy prompt into Codex or Claude.
3. Review the owner, status, dates and source link.
4. Open the browser view.
5. Confirm the original is unchanged.

Your next step

Use the same pattern for five approved documents, then build a small wiki:

• Build an Agent-Ready Wiki from Your Drive
• Keep Your Agent-Ready Wiki Safe and Trustworthy

Sources and notes

• CommonMark specification
• RFC 8259: JSON
• WHATWG HTML Living Standard
• W3C Web Content Accessibility Guidelines 2.2
• Mermaid documentation