Engineering on Artur Rios Lab

Asking for Help in Chat: No Hello, Don't Ask to Ask, and the XY Problem

Wed, 21 Oct 2026 23:00:00 +0000

Most of the time I spend helping someone, or being helped, goes to the question rather than the answer. The answer is often a sentence. Getting to the point where that sentence can be written takes a greeting, a wait, a follow-up, a “what are you actually trying to do?”, and another wait. In chat, each of those round trips can cost minutes or hours, because the other person is not watching the window.

The Conventions I Follow

Wed, 21 Oct 2026 18:00:00 +0000

A convention is a decision made once. Without them, every new repository, class and commit reopens the same small questions: what to call it, where to put it, how to phrase it. None of those questions is hard, but answering them again every time is slow, and answering them differently every time leaves a codebase that reads like it was written by several people who never met.

This page collects the conventions I follow in my own projects. Where a style guide already covers something, I follow it; the Google Style Guides are my default reference for the languages they cover. What is written here is either what those guides leave open, or a choice I have made on top of them.

How I Start a Project From Scratch

Wed, 21 Oct 2026 17:30:00 +0000

Every project on this site starts the same way. Not with code, but with a document, because the cheapest place to find a mistake is in a sentence, before anything has been built on top of it. This is the roadmap I follow, from the first idea to a system that is ready to use:

Create a brainstorm document for the project, with ideas about its nature, its implementation and the technologies to use.
Refine the brainstorm into four initial documents: Project Overview, Technology Stack, Workflow and Business Rules.
Formalise them into a Vision Document, a System Requirements Document and a Use Case Specification Document.
Review the documents, improve them, and review them again until they match what the project is meant to be.
Create GitHub issues for the initial scaffold and infrastructure.
Create a GitHub issue for each use case, linked to a GitHub Project and to an MVP milestone.
Implement the initial scaffold and infrastructure.
Implement one use case after another, including unit and functional tests.
For each use case, run the tests and fix until all of them pass, and only then move on to the next one.
Run a final test of the full functionality and fix any issue found, repeating until the system is ready.

The ten steps fall into four phases: