Rails

Short definition

The set of objects a development team makes available so that a third party — human or assistant — can produce on the code base without having to guess how it works: a catalogue of internal APIs, reusable components, conventions, framed environments, automatic checks, instruction files and skills.

Full definition

In ordinary usage, "laying rails" means preventing someone from leaving the road: the word belongs to the vocabulary of the guardrail, and it designates a limit imposed on someone you don't trust.

In the articles on this blog, the term keeps that sense but doesn't reduce to it, and it is the second sense that is the more operative: a rail is as much what shows the way as what prevents leaving it. A catalogue of internal APIs says what to call, a mapping between business concepts and technical entry points says where to go, reusable interface components save you rebuilding. What you gain by laying them isn't primarily safety, it is time — the time the assistant would spend searching, choosing the wrong entry point, or rewriting what already exists.

Rails are thus distinguished by their recipient: they don't serve whoever writes them, but those who produce afterwards.

Usage in the field

The term serves in platform investment trade-offs, and in the discussion about opening a code base to non-developer profiles. It allows the question to be put other than in terms of authorization: not "who is allowed to produce?" but "what has been prepared so that producing is possible?".

Synonyms and variants

"Internal platform", "foundation", "golden path" in platform engineering vocabulary. The word rails stays broader: it also covers the instruction files and skills meant for assistants, which platform vocabulary doesn't cover.

Not to be confused with

• Guardrail — an arrangement whose only function is to prevent a dangerous action. A security check in continuous integration is a guardrail; it is part of the rails, but the rails don't reduce to it.
• Directive — a written rule encoding a way of working for an agent. A directive is one of the possible rails, in the form of text read by the assistant.
• Documentation — text meant to be read by a human in order to understand. Some rails are documentation, others are executable objects: components, environments, checks.

Examples

An environment where a Product Manager composes internal screens, query builders, lists or charts leaning on documented and validated APIs, all the plumbing having been built by the developers.

Ambiguities / debates

The word is almost always heard in its restrictive sense, and that is what loses the arbitrations: presented as a protection, rails get negotiated against a delivery date. The tension between the two senses isn't settled in general usage; it is settled here in favour of the double sense.