Skip to content

Engineering Handbook

This is a handbook I wrote for engineering teams -- a practical guide to how we build software. It covers security, quality, observability, configuration, and delivery. I've used versions of it to align teams around shared standards and raise the bar on how we operate.

The content is preserved in its original voice. It was written for teams, not as a portfolio piece, and that's the point. Its available as a git repository: twistingmercury/my-engineering-handbook.

  • Security in Development

    Treating all input as hostile, managing secrets, vetting dependencies, and building security into the development process from day one.

  • Deliver Solutions that Work

    Definition of Done, testing standards, coverage thresholds, and what it means for a solution to actually work as expected.

  • The Importance of Documentation

    README structure, changelog standards, and operational documentation practices that keep knowledge accessible.

  • Managing Our Source

    Trunk-based development, branch naming, code review process, and keeping development branches short-lived.

  • Versioning Our Solutions

    Semantic versioning, pre-release conventions, CLI version flags, and Docker image labeling with OCI spec.

  • Builds and Deployments

    Container-based CI/CD pipelines, multi-stage Docker builds, end-to-end test infrastructure, and zero-downtime deployments.

  • Observability: Logging

    Structured JSON logging, log levels, what to log, what never to log, and resource utilization thresholds.

  • Observability: Distributed Tracing

    Trace context, what to trace, OpenTelemetry implementation, sampling strategies, and how tracing complements logging.

  • Observability: Metrics

    RED and USE methods, Prometheus implementation, cardinality management, and when to expose metrics.

  • Observability: Heartbeats, Readiness, and Liveness

    Unified health check endpoint design, resource utilization thresholds, and Kubernetes probe configuration.

  • Flexible Application Configuration

    Configuration precedence, secrets management, Docker/Kubernetes best practices, and fail-fast validation.

  • Scale & High Availability

    Planning for 10x growth, redundancy, load balancing, horizontal scaling, caching strategies, and auto-scaling.

  • Tooling Standards

    Cloud-agnostic technology choices, tool governance lifecycle, and the process for evaluating and adopting new tools.