Software Engineering #
I am collecting references that inspire me here.
Documentation #
I consider documentation an essential part of successfully scaling the engineering function. Clear, organized documentation reduces knowledge silos, accelerates onboarding, and ensures that engineering decisions are well-communicated across teams.
I like to categorize documentation into two primary types based on how long they remain relevant:
- Slowly Changing Documentation – Persistent records that evolve over time but remain useful for extended periods.
- Ephemeral (Short-Lived) Documentation – Temporary, task-driven documentation that loses relevance after a project or cycle ends.
Slowly Changing Documentation #
Slowly changing documentation forms the backbone of long-term knowledge. It evolves, but its core value persists over months or years. It provides context and reduces the need for repeated explanation.
Examples:
- Product Documentation
- Project Wikis
- System Architecture
- API Reference
- Onboarding Guides
- Coding Standards
- Operational Playbooks
To structure Slowly Changing Documentation I like to follow and advocate for the practices defined by Diatáxis which emphasizes the distinction between tutorials, how-to guides, explanations, and reference materials.
Ephemeral (Short-Lived) Documentation #
Ephemeral documentation serves immediate needs. It’s highly contextual, often created to support short-term goals, and typically discarded or archived once the project or cycle concludes.
Examples:
- Sprint Tickets
- Meeting Notes
- Ad-Hoc Project Plans
- Slack Discussions
- Whiteboard Drawings
- Email Threads
- Incident Reports (in draft form before becoming lessons learned)
Ephemeral documentation rarely outlives the project it was created for. Where valuable, key insights should be distilled into slowly changing documentation.
Versioning #
There is little to say when following Semantic Versioning: semver.org.
You can find some of my thoughts on data versioning in the dbt GitHub under [CT-2468] [Feature] For versioned models, automatically create view/clone of latest version in unsuffixed database location #7442.
Conventional Commits #
While inspiring, I don’t think Conventional Commits www.conventionalcommits.org are fully sufficient.
I like to follow branch name conventions that are somewhat like <branch-type>/<ticket>
where types are inspired by conventional commits e.g., build|ci|docs|feature|fix|....
For commit message I like to follow <type>(<ticket>)(!)?: <description>, where again the type is inspired by Conventional Commits. A full commit message could look something like this: feature(ABC-123)!: Breaking Change or build(ABC-123): Updated Build Pipeline.
The ticket in the commit message and branch name should to match with a Jira or Git Issue allowing full traceability between the systems.
Floating Point Arithmetic #
I guess everyone comes across a numerical issue eventually, and if it is just finding out that with float typing 0.1 + 0.2 is not equal to 0.3:
>>> 0.1+0.2 == 0.3
False
>>> 0.1+0.2
0.30000000000000004
I do recommend the classic What Every Computer Scientist Should Know About Floating-Point Arithmetic by David Goldberg to get a deep understanding of the topic.
Methodology #
Occasionally like to refer back to:
- The Twelve Factors: https://12factor.net/
- Microservices: https://microservices.io