# Docs Diataxis

> Diataxis Documentation Skill

- Skill: `neo4j-labs/docs-diataxis` (Agent Skill)
- Install (CLI): `npx skillmds@latest add neo4j-labs/docs-diataxis`
- Raw SKILL.md: https://api.skillmd.com/api/skills/neo4j-labs/docs-diataxis/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: neo4j-labs (https://skillmd.com/u/neo4j-labs)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/neo4j-labs/docs-diataxis

---

# Diataxis Documentation Skill

This skill provides guidance for working with the neo4j-agent-memory documentation, which follows the Diataxis framework.

## When to Use This Skill

Use this skill when:
- Adding new documentation pages
- Modifying existing documentation
- Deciding where to place new content
- Reviewing documentation for structure/style

## The Four Quadrants

### 1. Tutorials (`docs/tutorials/`)

**Purpose**: Learning-oriented. Help users learn by doing.

**Characteristics**:
- Step-by-step instructions
- Practical, hands-on lessons
- Focus on learning, not accomplishing
- Clear outcomes at each step
- Minimal explanation (link to Explanation for details)

**Writing Style**:
- Use "we will..." (inclusive)
- Provide exact commands/code to run
- Show expected output at each step
- Don't offer choices - provide one clear path

**Example titles**:
- "Build Your First Memory-Enabled Agent"
- "Create a Knowledge Graph from Documents"

### 2. How-To Guides (`docs/how-to/`)

**Purpose**: Task-oriented. Help users accomplish specific goals.

**Characteristics**:
- Problem-focused
- Assumes user knows what they want
- Practical steps to solve a problem
- No teaching, just doing

**Writing Style**:
- Start with the goal: "To do X, you need to..."
- Numbered steps for the solution
- Include prerequisites if needed
- End with verification/testing

**Example titles**:
- "Configure Entity Extraction"
- "Enable Location Geocoding"
- "Use with PydanticAI"

### 3. Reference (`docs/reference/`)

**Purpose**: Information-oriented. Provide facts for lookup.

**Characteristics**:
- Comprehensive and accurate
- Structure mirrors the code/product
- Austere, neutral tone
- Designed for scanning, not reading

**Writing Style**:
- Use tables for parameters/options
- Document ALL options, not just common ones
- Include types, defaults, constraints
- Keep descriptions factual and brief

**Example titles**:
- "Configuration Reference"
- "CLI Command Reference"
- "API Reference"

### 4. Explanation (`docs/explanation/`)

**Purpose**: Understanding-oriented. Help users understand concepts.

**Characteristics**:
- Discusses "why" not "how"
- Provides context and background
- Can include opinions and alternatives
- Discursive, can be read reflectively

**Writing Style**:
- Explain design decisions
- Discuss alternatives considered
- Connect to broader concepts
- Use diagrams for complex concepts

**Example titles**:
- "Understanding the Three Memory Types"
- "The POLE+O Data Model Explained"
- "How Entity Extraction Works"

## Decision Tree: Where Does Content Belong?

```
Is it about DOING something?
├── YES: Is it for LEARNING or ACCOMPLISHING?
│   ├── LEARNING → Tutorial
│   └── ACCOMPLISHING → How-To Guide
└── NO: Is it FACTS or UNDERSTANDING?
    ├── FACTS → Reference
    └── UNDERSTANDING → Explanation
```

## Common Mistakes to Avoid

1. **Don't mix quadrants**: A how-to guide shouldn't teach concepts (link to explanation instead)

2. **Don't put reference in tutorials**: Link to reference for complete option lists

3. **Don't explain in reference**: Keep reference factual; explanation goes elsewhere

4. **Don't make tutorials choose**: Provide one path, not options

## File Naming Conventions

- Use lowercase with hyphens: `entity-extraction.adoc`
- Use descriptive names: `first-agent-memory.adoc` not `tutorial-1.adoc`
- Integration guides: `how-to/integrations/{framework}.adoc`
- API reference: `reference/api/{component}.adoc`

## Cross-Referencing

Use `xref:` for internal links:
```asciidoc
See xref:explanation/memory-types.adoc[Understanding Memory Types] for conceptual background.

For configuration details, see xref:reference/configuration.adoc#extraction[Extraction Configuration].
```

## Adding New Content

1. Determine the quadrant using the decision tree above
2. Create the file in the appropriate directory
3. Add to the index page for that quadrant
4. Add cross-references from related pages
5. Run `npm run lint` to check for broken links

## Diagram and Screenshot Placeholders

For diagrams to be added later:
```asciidoc
.Architecture Overview
[cols="1", options="header"]
|===
| [DIAGRAM PLACEHOLDER: Memory Architecture]

a|
[source,text]
----
+------------------+
| MemoryClient     |
+------------------+
| Short | Long | R |
+------------------+
----
|===
```

For screenshots:
```asciidoc
[NOTE]
====
**[SCREENSHOT PLACEHOLDER]**

_Description: Neo4j Browser showing entity nodes and relationships_

Image to add: `images/screenshots/entity-graph.png`
====
```

## Building and Testing

```bash
cd docs
npm run build      # Build all pages
npm run serve      # Serve with live reload
npm run lint       # Check for broken links
```