Desarrollo

Plantilla de especificación técnica en Markdown

Esta plantilla de especificación técnica es un ejemplo resuelto, no un formulario vacío. Describe un servicio de pagos y muestra cómo un diagrama, una fórmula y un ejemplo de código conviven en un mismo documento. Sustituye el contenido por tu propio diseño y conserva la estructura.

Abrir esta plantilla en el editor

Categoría: Desarrollo
Estilo predeterminado: Técnico

Cuándo usarla

Escribe una especificación antes de construir algo que más de una persona deba aprobar. Los ingenieros la leen para revisar el diseño, y las personas de producto o control de calidad la leen para saber qué se va a lanzar. Una versión en PDF es adecuada para revisiones de diseño, aprobación del cliente y cualquier archivo donde el documento deba verse igual dentro de años.

Qué incluye

Una descripción general con campos para completar el proyecto y la persona responsable, seguida de un diagrama de secuencia Mermaid del flujo de la solicitud.
Una sección de presupuesto de reintentos con una fórmula en TeX, y un ejemplo en TypeScript en un bloque de código resaltado.
Un salto de página manual antes de la lista de preguntas abiertas, para que empiece en una página nueva.

Consejos para un mejor documento

Coloca el diagrama de flujo antes de los detalles. Quienes entienden primero la secuencia leen el resto de las secciones más rápido y hacen mejores preguntas.
Mantén las preguntas abiertas en la especificación hasta que alguien las responda, y luego traslada cada respuesta a la sección correspondiente. Para una especificación larga, añade una portada y un índice.

Vista previa de la plantilla

Especificación del servicio de pagos

Proyecto: Proyecto o tema Responsable: Tu nombre

Descripción general

El servicio de pagos recibe un pedido, cobra la tarjeta y registra el resultado. Las solicitudes son idempotentes durante 24 horas.

Flujo

sequenceDiagram
  participant App
  participant API
  participant Stripe
  App->>API: POST /charge
  API->>Stripe: create PaymentIntent
  Stripe-->>API: status
  API-->>App: receipt

Presupuesto de reintentos

Cada cliente puede reintentar con espera exponencial, donde la espera tras el intento $n$ es

w_n = \min(2^n \cdot 250\,\text{ms},\ 8\,\text{s})

Ejemplo

export const charge = async (order: Order) => {
  const intent = await stripe.paymentIntents.create({ amount: order.total });
  return { id: intent.id, status: intent.status };
};

Preguntas abiertas

¿Guardamos los últimos cuatro dígitos?
¿Qué monedas se lanzan primero?

Los campos por completar, como tu nombre y la fecha, se sustituyen cuando abres la plantilla en el editor.