Dev Notes

Dev Notes

A curated, structured collection of personal developer knowledge: architecture decisions, design patterns, coding standards, deployment strategies, career notes, tools, and productivity tips. Think of it as a fast, searchable second brain you can evolve over time.

Repository Structure

Top-level domains map to broad areas of practice:

| Path | Focus | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | career/ | Career development, job search, contracting, certification notes | | coding/ | Core engineering topics (APIs, architecture, deployments, patterns, git, code quality, observability, language specifics) | | coding/apis/rest-api/ | REST design conventions: methods, naming, versioning, etc. | | coding/architecture/ | Diagrams, decisions, assets, architecture practices | | coding/deployments/ | Release strategies (blue/green, canary, feature toggles, IaC, CI/CD) | | coding/design-patterns/ | Classic patterns distilled (adapter, strategy, state, etc.) | | coding/git/ | Workflow guidance: branching, hooks, PRs, commit messages | | coding/good-code/ | Principles: SOLID, DDD, 12-factor, YAGNI, value objects, cognitive load | | coding/laravel/ | Laravel standards, Pint config, best practices | | coding/observability/ | Logging, monitoring, alerting, health checks | | coding/php/ | PHP standards, static analysis (PHPStan), Rector automation | | composer/ | Composer scripts and related docs | | docker/ | Docker maintenance & cleanup | | gcp/ | Cloud provider specifics (e.g. GCP VM port forwarding) | | github/ | GitHub automation, workflows, Dependabot, releases | | tools/ | Productivity & business tool references | | vscode/ | Editor settings and recommended tweaks |

Writing & Organising Notes

Principles:

  1. Make each note answer ONE intent quickly.
  2. Prefer concise bullet points over prose when clarity isn't lost.
  3. Link related notes (relative markdown links) to build a knowledge graph.
  4. Use examples (code / commands) minimally but concretely.
  5. Keep vendor-neutral unless specifics add real value.

Conventions:

  • File naming: kebab-case.md for readability in terminals.
  • Group by concept before technology (e.g. observability/logging.md).
  • Avoid duplication—link instead of copy/paste repeating concepts.
  • If a concept evolves, add a small CHANGELOG section or reference an architecture decision.
  • Use present tense, active voice.

Adding a New Note

  1. Pick or create the right folder (avoid deep nesting unless necessary).
  2. Create topic-name.md with: purpose (1–2 lines), core principles, actionable steps, pitfalls, references.
  3. Cross-link at least one related existing note.
  4. (If code standard) reference supporting tools or configs in repo.
  5. Commit with a conventional style (see coding/git/commit-messages.md).

Example skeleton:

# Feature Toggles
Purpose: Safely deploy incomplete features by decoupling deploy from release.

## When to Use
... concise bullets ...

## Implementation Tips
... code or config examples ...

## Risks / Mitigations
...

## Related
../deployments/blue-green.md