Skip to content

📘 Handbook Update Contract

This document defines how the Embedded Linux Learning Handbook should be updated after each learning session.

The goal is to keep the repository maintainable, topic-oriented, and scalable without requiring large-scale refactoring in the future.

🎯 Philosophy

The handbook follows several principles:

  • Handbook-first organization
  • Topic-oriented knowledge structure
  • Minimal required updates
  • Incremental growth
  • Long-term maintainability

Learning history remains preserved through logs and labs, while reusable knowledge is extracted into topics and references.

🧩 Repository Architecture

learning-log/

Purpose:

Daily learning record.

Contents:

  • Learning summary
  • Daily achievements
  • Reflections
  • Future plans

Examples:

learning-log/
├── day58.md
├── day59.md

labs/

Purpose:

Hands-on implementation and experiments.

Contents:

  • Code walkthrough
  • Test steps
  • Validation result
  • Scripts

Examples:

labs/
├── day58-posix-semaphore-ipc.md
├── day59-io-uring.md

notes/

Purpose:

Extract reusable concepts from labs.

Contents:

  • Concept explanation
  • Architecture discussion
  • Design decisions

Notes should NOT duplicate lab content.

topics/

Purpose:

Long-term handbook knowledge.

Contents:

  • Architecture overview
  • Learning map
  • Related labs
  • Related notes
  • Related APIs

Topics represent stable knowledge.

api-reference/

Purpose:

Quick Linux API lookup.

Contents:

  • Prototype
  • Parameters
  • Return value
  • Minimal example
  • Pitfalls
  • Related labs

Only create API reference if the API provides reusable value.

meta/

Purpose:

Repository maintenance.

Contents:

  • Refactor history
  • Deployment guide
  • Troubleshooting
  • Repository rules

🔄 Daily Update Workflow

After finishing each learning session:

Learn
 ↓
Create log
 ↓
Create lab
 ↓
Evaluate reusable knowledge
 ↓
Update handbook if necessary
 ↓
Build and deploy

✅ Required Updates

Always perform:

  • Update learning-log
  • Create or update lab

🔍 Optional Updates

Only update when necessary:

  • Create or update notes
  • Create or update topics
  • Update API reference
  • Update troubleshooting
  • Update roadmap
  • Update homepage

🧠 Decision Rules

New architecture appears

Examples:

  • Event loop
  • Driver model
  • USB stack

Action:

Update topics/

New Linux API appears

Examples:

  • io_uring
  • mmap
  • epoll

Action:

Update api-reference/

New debugging experience appears

Conditions:

  • Debugging took significant effort
  • Root cause is reusable

Action:

Update troubleshooting/

New learning direction appears

Examples:

  • Begin USB
  • Begin Yocto
  • Begin tracing

Action:

Update roadmap

Homepage changes only when:

  • Major topic added
  • Handbook structure changes

Otherwise:

No homepage update required

📦 Expected Output

When requesting handbook updates, output should include:

Patch Summary

Brief explanation of changes.

Files Changed

Example:

Modified:
- learning-log/day59.md
- labs/day59-io-uring.md

Added:
- topics/io-uring.md
- api-reference/io-uring/

Commit Suggestion

Example:

docs: add io_uring notes and API references

Deployment Impact

State whether:

  • rebuild required
  • navigation changed
  • Cloudflare deployment affected

🚀 Standard Workflow

Development:

mkdocs serve

Validation:

mkdocs build --strict

Commit:

git commit

Release:

main
 ↓
deploy
 ↓
Cloudflare Pages

📌 Daily Command

After learning finishes:

Update the handbook according to Handbook Update Contract.

This instruction means:

  • generate log
  • generate lab
  • evaluate notes
  • evaluate topics
  • evaluate API references
  • evaluate troubleshooting
  • suggest commit
  • suggest deployment impact

without requiring additional explanation.