Guías de escritura

MDN Web Docs es un proyecto de código abierto. Las secciones que se describen a continuación describen nuestras pautas para lo qué documentamos y cómo lo hacemos en MDN Web Docs. Para conocer cómo contribuir consulta nuestras guías de contribución.

Lo que escribimos

Esta sección cubre lo que incluimos en MDN Web Docs y lo que no, así como una serie de otras políticas, como cuándo escribimos sobre nuevas tecnologías, el proceso de sugerencia de contenido y si aceptamos enlaces externos. Este es un buen lugar para comenzar si está considerando escribir o actualizar contenido para nosotros. Esta sección también incluye:

Criterios de inclusión

Proporciona criterios detallados para que el contenido se incluya en MDN Web Docs, el proceso de solicitud para agregar nueva documentación en MDN Web Docs y las expectativas y pautas para la parte que solicita.

Nuestra guía de estilo de escritura

La guía de estilo de escritura cubre el idioma y el estilo que usamos para escribir en MDN Web Docs. También cubre cómo formatear ejemplos de código.

Cómo escribir para MDN Web Docs

Esta sección cubre toda la información para crear y editar páginas, incluidos ciertos procesos y técnicas a los que nos adherimos. Esta sección proporciona información sobre cómo comenzar, una descripción general de cómo se estructuran las páginas y dónde encontrar instrucciones sobre tareas específicas. Esta sección incluye temas como:

Cómo investigar una tecnología

Esta sección proporciona algunos consejos útiles para investigar una tecnología que está documentando.

Cómo crear, mover y eliminar páginas

Esta sección explica cómo creamos, movemos o eliminamos una página en MDN Web Docs. También explica cómo redirigimos una página al mover o eliminar la página.

Cómo usar markdown

El formato markdown que usamos se deriva de la versión markdown de GitHub (GFM, por sus siglas en inglés). Esta sección es una guía de la versión markdown que usamos en MDN Web Docs, incluidos los formatos para componentes específicos en la página, como notas y listas de definiciones.

Añadiendo imágenes y medios

En esta sección se describen los requisitos para incluir contenido multimedia en las páginas, como imágenes.

Cómo documentar una propiedad CSS

Este artículo explica cómo escribir una página de propiedades CSS, incluido el diseño y el contenido.

Cómo documentar una referencia de API

Esta sección explica cómo abordar la documentación de una API web.

Cómo documentar una cabecera HTTP

Este artículo explica cómo crear una nueva página de referencia para una cabecera HTTP.

Cómo agregar una entrada al glosario

Este artículo explica cómo agregar y vincular entradas en el glosario de MDN Web Docs. También proporciona pautas sobre el diseño y el contenido de las entradas del glosario.

Tipos de página en MDN Web Docs

Cada página de MDN Web Docs tiene un tipo de página específico, ya sea una página de referencia de CSS o una página de guía de JavaScript. Esta sección enumera los diferentes tipos de página y proporciona plantillas para cada tipo. Es una buena idea examinarlos para comprender qué tipo de página está escribiendo.

Estructuras de página en MDN Web Docs

Esta sección cubre las diversas estructuras de página que usamos para proporcionar una presentación coherente de la información en MDN Web Docs. Esto incluye:

Secciones de sintaxis

La sección de sintaxis de una página de referencia en MDN Web Docs contiene un cuadro de sintaxis que define la sintaxis exacta de una característica. Este artículo explica cómo escribir cuadros de sintaxis para artículos de referencia.

Ejemplos de código

Hay muchas maneras diferentes de incluir ejemplos de código en las páginas. Esta sección los describe y proporciona pautas de sintaxis para los diferentes lenguajes.

Banners y avisos

A veces, un artículo necesita que se le agregue un aviso especial. Esto podría suceder si la página cubre tecnología obsoleta u otro material que no debería usarse en el código de producción. Este artículo cubre los casos más comunes y cómo manejarlos.

Tablas de especificaciones

Cada página de referencia en MDN Web Docs debe proporcionar información sobre la especificación o especificaciones en las que se definió esa API o tecnología. Este artículo muestra el aspecto de estas tablas y explica cómo agregarlas.

Tablas de compatibilidad

MDN Web Docs tiene un formato estándar para tablas de compatibilidad para nuestra documentación web abierta. Este artículo explica cómo agregar y mantener la base de datos que se utiliza para generar las tablas de compatibilidad y cómo integrar las tablas en los artículos.

Macros

Las macros son accesos directos que se utilizan en las páginas para generar contenido, como los menús laterales. Esta sección enumera las macros que usamos y lo que hacen.

Atribuciones e información sobre licencias de derechos de autor

Describe nuestra política sobre el uso de contenido de MDN Web Docs en otros lugares de la web, cómo obtener permiso para volver a publicar contenido en MDN y sugerencias para vincular contenido de MDN.

Cómo etiquetar una tecnología

Esta sección cubre nuestras definiciones de los términos obsoleto, en desuso y experimental y proporciona pautas sobre cómo etiquetar una tecnología con ellos y cuándo eliminamos contenido de MDN Web Docs.