Cómo documentar una cabecera HTTP

Paso 1 – Determina la cabecera HTTP para documentar

• Hay muchas cabeceras HTTP definidas en varios estándares IETF.
• IANA mantiene un registro de campos de cabecera HTTP y Wikipedia enumera los campos de cabecera conocidos, pero no todos son relevantes para los desarrolladores web o forman parte de un estándar oficial.
• Si hay enlaces rojos en la página de descripción general de referencia de cabeceras HTTP actual, estas cabeceras son una buena opción para documentar.
• En caso de duda, pregunta al equipo de MDN Web Docs si tiene sentido o no escribir sobre la cabecera que has elegido.

Paso 2 – Verifica las páginas de cabeceras HTTP existentes

• Las cabeceras HTTP existentes se documentan en la referencia de HTTP.
• Existen diferentes categorías de cabeceras: Cabecera de solicitud, Cabecera de respuesta y Cabecera de representación.
• Busca la categoría de la cabecera que vas a documentar (ten en cuenta que algunas pueden ser tanto de solicitud como de respuesta, dependiendo del contexto).
• Busca una página de referencia de cabecera existente que pertenezca a la misma categoría.

Paso 3 – Crea la página de la cabecera HTTP

• Todas las páginas de cabeceras residen bajo este árbol: files/en-us/web/http/reference/headers.
• Para crear una nueva página, consulta las instrucciones en nuestra guía sobre cómo crear una página.

Paso 4 – Escribe el contenido

• Puedes comenzar desde nuestra plantilla de página de cabecera HTTP o usar una estructura copiada de uno de los documentos de cabeceras existentes que encontraste en el paso 2. Tú eliges.
• Escribe sobre la nueva cabecera HTTP.
• Asegúrate de incluir estas secciones:
  • Texto introductorio donde la primera oración mencione el nombre de la cabecera (en negrita) y resuma su propósito.
  • Cuadro de información que contenga al menos el tipo de cabecera y si es una Cabecera de solicitud prohibida.
  • Un cuadro de sintaxis que contenga todas las directivas/parámetros/valores posibles de la cabecera HTTP.
  • Una sección que explique estas directivas/valores.
  • Una sección de ejemplos que contenga un caso de uso práctico para esta cabecera o muestre dónde y cómo ocurre normalmente.
  • Una sección de especificaciones que enumere los documentos estándar RFC relevantes.
  • Una sección "Véase también" con recursos relacionados.

Paso 5 – Agrega información de compatibilidad con navegadores

• Si has observado otras páginas de cabeceras HTTP, verás que existe una macro {{Compat}} que generará automáticamente una tabla de compatibilidad por ti.
• La tabla de compatibilidad se genera a partir de datos estructurados. Si deseas contribuir con los datos, consulta las instrucciones en https://github.com/mdn/browser-compat-data/blob/main/README.md y envíanos un pull request.

Paso 6 – Actualiza la lista de cabeceras HTTP

Asegúrate de que tu cabecera aparezca en la categoría apropiada en la página de descripción general de referencia de cabeceras HTTP.

Paso 7 – Solicita una revisión del contenido

Después de crear la página de la cabecera, envíala mediante un pull request. Se asignará automáticamente a un miembro de nuestro equipo de revisión para que evalúe tu página.