Workflow - Creating and Updating Notes

This document describes the correct workflow for creating and updating notes to avoid incomplete documents and broken links.

Creating Child Notes with Links

CORRECT ORDER: Create children first, then update parent

When you need to create multiple related notes:

1. Create all child notes first using notes load -d with complete content

2. THEN update the parent page to add links to the children

3. Verify all links resolve correctly

Why This Order?

• Avoids uploading incomplete parent documents with empty sections

• Child notes exist before being referenced

• Clear sequential workflow - no partial states

• Easier to verify completeness before linking

Example: Documenting a New Feature

Suppose you want to document a new feature with three aspects: design, implementation, and testing.

Step 1: Create child notes with full content

# Create /tmp/design.json with complete content
notes load -d project/feature-design /tmp/design.json

# Create /tmp/implementation.json with complete content
notes load -d project/feature-implementation /tmp/implementation.json

# Create /tmp/testing.json with complete content
notes load -d project/feature-testing /tmp/testing.json

Step 2: Read parent to preserve existing content

notes read project

Step 3: Update parent with links to children

# Create /tmp/project-updated.json
# Preserve all existing content and metadata
# Add new section with links to the three child notes
notes load -d project /tmp/project-updated.json

WRONG: Don't Upload Partial Documents

DO NOT do this:

❌ Upload parent with links to children that don't exist yet

❌ Upload parent with placeholder sections like "TODO: add content"

❌ Upload parent, then realize you need to add children, then update again

Why Not Hanging Links?

While JSONHTL permits links to non-existent documents, uploading a parent with hanging links creates confusion:

• Readers see broken links and think content is missing

• Harder to track what's complete vs incomplete

• Creates intermediate incomplete state

Updating Existing Notes

When modifying an existing note:

1. notes read <key> to get current content

2. Create updated JSON file preserving:

• All existing links to children

• Metadata: title, version (increment it), created, tags

• Add updated: YYYY-MM-DD field

3. notes load -d <key> /tmp/updated.json

4. Verify update with notes read <key>

Quick Reference

Creating linked notes:

1. Create all children (complete content)

2. Read parent

3. Update parent to link children

Updating existing note:

1. Read current version

2. Preserve metadata and links

3. Increment version, add updated date

4. Upload new version

See also: Avoiding Orphaned Notes