Documentación de programación

¿Para qué sirve una guía HTML o documentación de sitios web?

La creación de un sitio web implica el desarrollo de funcionalidades basadas en tecnologías y estándares. Estas decisiones incluyen escoger lenguajes de programación y técnicas para todo el proyecto, las que deben ser respetadas para su correcto funcionamiento.

¿Cómo aseguramos que todos los integrantes del equipo manejen estas decisiones? Elaborando una guía HTML o documentaciones. En este entregable explicamos cómo funciona el sitio web, considerando la estructura de su código, los elementos y las funcionalidades.

¿A quién dirigir la guía HTML y en qué momento se entrega?

Apunta a desarrolladores, analistas y cualquier profesional que realice modificaciones en el código de la plataforma. Esta documentación se envía junto al manual de WordPress para los gestores de contenido y la guía de normas gráficas para los diseñadores.

Un manual HTML tiene especial importancia en sitios complejos donde no se compromete una mantención de parte de los creadores.

¿Qué elementos deben ir en la documentación HTML?

Todas las documentaciones son diferentes. Cada una de sus secciones se adaptan para describir las funcionalidades de la plataforma. Por ejemplo, si se trata de un sitio con gráficos en JavaScript, incluiremos un apartado dedicado a explicar su configuración y funcionamiento.

Aún así, existen secciones generales que se repiten en gran parte de los proyectos. Estas son:

Estructura de archivos

Describe la organización de las carpetas que contienen los archivos del desarrollo front end y back end. Usualmente se clasifican según su extensión, por ejemplo .html, .css o .js.

Atributos personalizados

Para programar funcionalidades especiales es posible usar atributos personalizados en HTML5, los cuales son reconocibles gracias al prefijo “data-”. Esta sección incluye una descripción de estos atributos. Además, se entrega un detalle de las partes en que se ha implementado JavaScript, sus funciones en el sitio y cómo se conecta con el código HTML.

Hojas de estilo CSS3

Los archivos de estilo del proyecto se dividen en dos categorías. La primera contiene la grilla responsiva del sitio (grid.css), la cuál permite que el sitio se adapte correctamente a las distintas pantallas. La otra reúne los elementos de estilo (style.css), que incluye especificaciones como:

• Declaración de las reglas.
• Estilos auxiliares.
• Estilos generales.
• Definiciones para Tablets.
• Normas para Smartphones.

HTML5

Describe la estructura HTML5 del proyecto. Especifica los elementos, etiquetas, IDs y clases necesarias para el correcto funcionamiento del sitio web.

En lo global, esta contiene:

• Un elemento <header>, en el cual se encuentra el logo y la navegación principal.
• Un elemento <section> o <article> con los elementos e información principal.
• Un elemento <footer> con la navegación principal, el logo y la información de contacto.

Marcas de Google Analytics

Especifica los códigos de seguimiento de analítica insertados en el sitio. Estas marcas se entregan configuradas para recopilar datos sobre el comportamiento de los usuarios y analizar la efectividad de las acciones propuestas. Cuando el administrador del sitio necesite optimizar o adaptar sus mediciones, tendrá que consultar esta sección para entender dónde y cómo se han aplicado estos códigos.

¿Qué ocurre si no se consulta la documentación?

En desarrollo web existen muchas formas de hacer una misma cosa. Si estas decisiones no siguen una lógica y mantienen una coherencia, el sistema puede presentar errores o dejar de funcionar. La documentación tiene como objetivo principal comunicar esta lógica. De esta forma se asegura que las modificaciones futuras se ejecuten siguiendo las mismas reglas.

El diseño y desarrollo de un sitio web es un proceso adaptativo, donde no existen productos perfectos sino perfectibles. Por esto, los cambios según la interacción de los usuarios y los objetivos del proyecto, pueden ser frecuentes.

Si se ignora este documento, lo más probable es que el sitio web presente errores graves luego de hacer cambios en él. Esto puede traer consecuencias que afecten negativamente la experiencia de los usuarios. Recomendamos revisar con cuidado esta información y mantener cerca una copia de consulta.

Si deseas más orientación respecto al desarrollo de plataformas digitales orientadas a los usuarios, contáctanos para asegurar el éxito de tu proyecto digital.