Skip to content

Handbook Update Contract

Purpose

This document defines the standard workflow for updating the Embedded Linux Learning Handbook after completing a learning session.

Its purpose is to ensure every completed topic is consistently integrated into the handbook, keeping all documents synchronized and preventing missing updates.

This document focuses on what should be updated.

Documentation style, writing conventions, templates, and diagram standards are maintained separately in handbook-style-guide.md.

Repository Structure

The handbook is organized into four primary documentation layers.

Learning Log
        │
        ▼
Labs
        │
        ▼
Topics
        │
        ▼
API Reference

Each layer serves a different purpose.

Layer Purpose
Learning Log Record what was learned during a specific day.
Labs Provide reproducible experiments and implementation examples.
Topics Organize reusable concepts independent of individual learning days.
API Reference Document reusable Linux APIs and kernel interfaces.

Daily Update Workflow

After completing a learning session, update the handbook in the following order.

Learning Log
        │
        ▼
Lab
        │
        ▼
Topic
        │
        ▼
API Reference
        │
        ▼
Navigation
        │
        ▼
Commit
        │
        ▼
Next-Day Handoff

Update Checklist

1. Learning Log

Create or update:

docs/log/dayXX.md

The learning log records:

  • Today's goal
  • What was learned
  • Important observations
  • Summary
  • Next plan

2. Labs

Create or update:

docs/labs/dayXX/

Labs should contain:

  • Goal
  • Environment
  • Implementation
  • Verification
  • Expected output
  • Summary

3. Topics

Create or update reusable topic pages.

Topics should describe reusable concepts instead of daily progress.

Typical location:

docs/topics/

4. API Reference

Create or update reusable API reference pages.

Typical location:

docs/api-reference/

5. Diagram Integration

If the current learning topic introduces new reusable diagrams:

  • Complete all diagram source files (.drawio) before updating Topic pages.
  • Export the final .svg files before writing surrounding explanations.
  • Replace obsolete ASCII diagrams with SVG diagrams instead of keeping both.
  • Ensure every referenced SVG is actually used by at least one handbook page.
  • Keep diagram filenames stable after publication.
  • Store reusable diagrams under:
docs/assets/diagrams/

Update Topic pages only after the final diagrams have been completed.

  • Perform one final review after all diagrams have been integrated to remove duplicated ASCII diagrams or outdated explanations.

6. Navigation

Update handbook navigation whenever new pages are added.

Possible files include:

mkdocs.yml

docs/topics/index.md

docs/api-reference/index.md

docs/labs/index.md

Update only the files affected by the current learning topic.

7. Cross References

Review related links between:

  • Labs
  • Topics
  • API References

Ensure newly added pages are properly connected.

8. Final Consistency Review

Before preparing the commit:

  • Remove obsolete "Coming Soon" sections that have been completed.
  • Remove duplicate ASCII diagrams replaced by SVG diagrams.
  • Verify all Topic, API Reference, and Lab links.
  • Verify every SVG referenced in Markdown exists and renders correctly.
  • Check that diagrams and surrounding text remain consistent.
  • Review the final Topic page from top to bottom instead of patching individual sections.
  • When a page has undergone multiple incremental edits, regenerate or reorganize the entire page instead of continuing to patch individual sections.

9. Commit

Prepare a concise commit message.

Preferred format:

docs: <summary>

Examples:

docs: add DMA Engine framework overview

docs: update kernel memory documentation

10. Next-Day Handoff

Prepare a handoff summary containing:

  • Current progress
  • Next learning topic
  • Outstanding TODO items
  • Repository changes that should continue tomorrow

This allows the next conversation to continue without losing context.

Completion Checklist

Before ending the learning session, confirm:

  • Learning Log updated
  • Lab completed
  • Topics updated
  • API References updated
  • Navigation updated
  • Cross references reviewed
  • Diagrams reviewed (if applicable)
  • Final consistency review completed
  • Commit message prepared
  • Next-day handoff prepared

Expected Output

A completed learning session should produce:

  • Updated learning log
  • Runnable lab
  • Reusable topic documentation
  • Reusable API documentation
  • Updated handbook navigation
  • Clean Git history

Scope

This document defines the update process only.

For documentation style, writing conventions, templates, diagram standards, naming conventions, and assets organization, refer to:

handbook-style-guide.md