RFCs and technical proposals

RFCs (Request for Comments) and technical proposal documents are a common tool for making design decisions in an explicit, reviewable, and shared way.

They are usually long, argumentative, and living documents, combining narrative text with structured information.

What we mean here by RFC

In this context, “RFC” includes:

• Internal technical proposals.
• Classic RFCs inspired by the IETF.
• ADRs (Architecture Decision Records, records of architecture decisions).
• Design documents prior to implementation.

No specific process is assumed: the focus is on the document, not the methodology.

Common problems with current RFCs

In practice, these documents often:

• Live in Markdown with implicit conventions.
• Mix metadata with free text without clear separation.
• Depend on human discipline to maintain structure.
• Be difficult to validate automatically.

Even so, the workflow is usually good:

• Plain text.
• Versioned in Git.
• Reviewed by diff.

STXT does not replace that workflow: it reinforces it.

Example 1 — Minimal RFC

A very small RFC, sufficient for initial discussion.

RFC (@com.acme.rfc):
	Id: RFC-012
	Title: Distributed cache for module X
	Status: Draft
	Authors:
		Author: Joan Costa
	Created: 2026-01-11

	Context >>
		Module X has latency problems under load.
		Currently each instance queries the database
		for repetitive operations.

	Proposal >>
		Introduce a shared distributed cache layer
		across instances to reduce database accesses.

	Decision >>
		Pending evaluation.

What STXT brings here

• Long text lives in >> blocks, without restrictions.
• Metadata are clear nodes, not conventions.
• The RFC structure is visible at a glance.

Example 2 — More complete RFC

A realistic RFC with alternatives, impact, and risks.

RFC (@com.acme.rfc):
	Id: RFC-013
	Title: Unification of the configuration system
	Status: Review
	Authors:
		Author: Platform Team
	Created: 2026-01-05
	Updated: 2026-01-10

	Context >>
		Currently there are multiple configuration formats
		(JSON, YAML, properties) with different rules.

	Problem >>
		The diversity of formats makes validation,
		automation, and support difficult.

	Proposal >>
		Adopt STXT as the single configuration format
		for internal services.

	Alternatives:
		Alternative:
			Title: Keep current formats
			Pros >>
				Zero initial cost.
			Cons >>
				Fragmentation remains.

		Alternative:
			Title: Standardize on YAML
			Pros >>
				Existing tools.
			Cons >>
				Ambiguity and complex validation.

	Impact >>
		Teams will need to gradually migrate their configurations.

	Risks >>
		Initial resistance to change.

	Decision >>
		Under architecture review.

Example 3 — Status evolution

An RFC usually changes status over time. The status is explicit data, not a sentence in the text.

RFC (@com.acme.rfc):
	Id: RFC-013
	Title: Unification of the configuration system
	Status: Accepted
	Accepted date: 2026-01-18

	Decision >>
		The progressive adoption of STXT is approved
		as the standard configuration format.

	Consequences >>
		* New services will use STXT.
		* Existing ones will migrate incrementally.

Example 4 — Relationship between RFCs

It is common to reference other documents. In STXT, these relationships can be explicit.

RFC (@com.acme.rfc):
	Id: RFC-020
	Title: Deprecation of the legacy system
	Status: Draft

	Related:
		RFC: RFC-013
		RFC: RFC-007

	Context >>
		This RFC depends on the adoption of the new configuration system
		described in RFC-013.

Example 5 — Comments and review

An RFC can accumulate comments without mixing them with the main text.

RFC (@com.acme.rfc):
	Id: RFC-021
	Title: New deployment pipeline
	Status: Review

	Proposal >>
		Unify CI/CD pipelines into a single definition.

	Comments:
		Comment:
			Author: Mery Adams
			Date: 2026-01-12
			Text >>
				I’m concerned about the impact on teams with their own tooling.

		Comment:
			Author: Keyla Brown
			Date: 2026-01-13
			Text >>
				Has the migration cost been evaluated?

Example 6 — Minimal template for RFCs

If coherence is desired without rigidity, a lightweight template can ensure that no RFC is incomplete.

Template (@stxt.template): com.acme.rfc
	Description: Minimal structure for technical RFCs
	Structure >>
		RFC:
			Id: (1)
			Title: (1)
			Status: (1) ENUM [Draft, Review, Accepted, Rejected, Deprecated]
			Authors: (1)
				Author: (+)

			Context: (1) TEXT
			Proposal: (1) TEXT
			Decision: (?) TEXT

			Alternatives: (?)
				Alternative: (*)
					Title: (1)
					Pros: (?) TEXT
					Cons: (?) TEXT

			Impact: (?) TEXT
			Risks: (?) TEXT
			Comments: (?)

Why this case fits especially well

RFCs are already:

• Plain text.
• Versioned in Git.
• Reviewed by people.

STXT adds:

• Explicit structure.
• Processable metadata.
• Optional validation.
• Less dependence on implicit conventions.

Without changing the nature of the document.

Summary

Using STXT for RFCs and technical proposals makes it possible to:

• Write clear, well-argued documents.
• Keep structure visible and consistent.
• Facilitate review, automation, and traceability.

All without turning the document into a formal language or into code.