Saltar al contenido

La importancia de la documentación para desarrolladores web

doc examples

En el ámbito del desarrollo de aplicaciones móviles, web y de escritorio o bibliotecas JavaScript, la documentación desempeña un papel importante para determinar el éxito de la aplicación. Pero si alguna vez ha realizado documentación, estaría de acuerdo conmigo en que es prácticamente la cosa menos favorita que hacen los desarrolladores.

A diferencia de la escritura de código (que es para lo que los desarrolladores se inscribieron), la documentación debe ser digerida fácilmente por todos. Técnicamente, tenemos que traducir un lenguaje de máquina (código) a un lenguaje que sea comprensible para los humanos, que es más difícil de lo que parece.

Aunque puede ser una carga real, redactar la documentación es importante y ofrecerá ventajas para sus usuarios, sus colegas y, especialmente, para usted.

Programación de aprendizaje: 10 conceptos erróneos que no son ciertos

Programación de aprendizaje: 10 conceptos erróneos que no son ciertos

Hay muchos conceptos erróneos y mitos en torno al arte de la programación. Muchos lo ven como un trabajo … Leer más

Una buena documentación ayuda a los usuarios

La documentación ayuda al lector entender cómo funciona un código, obviamente. Pero muchos desarrolladores cometen el error de asumir que los usuarios del software serán competentes.

Por lo tanto, la documentación puede ser un material delgado, saltándose muchos de los elementos esenciales que debería haber contenido desde el principio. Si eres experto en el idioma, puedes resolver las cosas por tu propia iniciativa; si no lo estás, estás perdido.

La documentación destinada a los usuarios suele consistir en un uso práctico o en el «cómo hacerlo». La regla general al crear documentación para usuarios generales es que debe estar bien definido. Es preferible usar palabras amigables con los humanos a términos técnicos o jerga. Los ejemplos de uso real también serán muy apreciados.

Un buen diseño de diseño también ayudaría realmente a los usuarios a escanear cada sección de la documentación sin fatiga visual. Algunos buenos ejemplos (también conocidos como mis favoritos) son la documentación para Bootstrap y los “Primeros pasos con WordPress” de WordPress.

Ayuda a otros desarrolladores

Cada desarrollador tendrá su propio estilo de codificación. Pero, cuando se trata de trabajar en equipo, a menudo tendremos que compartir códigos con otros compañeros de equipo. Por eso es fundamental tener un consenso sobre un estándar para mantener a todos en la misma página. Una documentación debidamente redactada sería la referencia que el equipo necesita.

Pero a diferencia de la documentación del usuario final, esta documentación generalmente describe procedimientos técnicos como la convención de nomenclatura de código, que muestra cómo se deben construir páginas particulares y cómo funciona la API junto con los ejemplos de código. A menudo, también tendríamos que escribir la documentación en línea con el código (conocido como comentarios) para describir lo que hace el código.

Además, en el caso de que tenga nuevos miembros que se unen su equipo más tarde, esta documentación podría ser una forma eficaz de capacitarlos, de modo que no tenga que darles un análisis 1 a 1 del código.

Diez hábitos de programación que los desarrolladores deben adoptar

Diez hábitos de programación que los desarrolladores deben adoptar

Estos resultados pueden reducir nuestra confianza pero, de hecho, pueden resolverse con prácticas de desarrollo adecuadas … Leer más

También ayuda al propio codificador

Lo curioso de la codificación es que a veces incluso los propios desarrolladores no comprenden el código que han escrito. Esto es particularmente cierto en los casos en que los códigos se han dejado intactos durante meses o incluso años.

Una necesidad repentina de revisar los códigos por una razón u otra dejaría a uno preguntándose qué estaba pasando por sus mentes cuando escribieron estos códigos. No se sorprenda: he estado en esta situación antes. Este es precisamente cuando yo deseado Había documentado mi código correctamente.

Al documentar sus códigos, podrá llegar al final de sus códigos rápidamente y sin frustración, lo que le permitirá ahorrar mucho tiempo que puede dedicar a realizar los cambios.

¿Qué hace que la documentación sea buena?

Hay varios factores que ayudan a crear una buena documentación. Algunos de los más importantes son los siguientes:

1. Nunca asuma

No asuma que sus usuarios saben qué usted saber tan bien como ellos quieren saber. Siempre es mejor para empezar desde el principio independientemente del nivel de competencia de los usuarios.

Si creó un complemento de jQuery, por ejemplo, puede inspirarse en la documentación de SlickJS. Muestra cómo estructurar el HTML, dónde poner CSS y JavaScript, cómo inicializar el complemento jQuery en su nivel más básico, e incluso muestra el marcado final completo después de agregar todas estas cosas, lo cual es algo obvio.

La conclusión es que la documentación está escrita con el proceso de pensamiento de un usuario, no de un desarrollador. Acercarse a su propia documentación de esta manera le dará una mejor perspectiva para organizar su propia pieza.

2. Siga el estándar

Al agregar documentación que va en línea con el código, utilizar el estándar esperado del idioma. Siempre es una buena idea describir cada función, las variables, así como el valor devuelto por la función. Aquí hay un ejemplo de buena documentación en línea para PHP.

/**
 * Adds custom classes to the array of body classes.
 *
 * @param array $classes Classes for the body element.
 * @return array
 */
function body_classes( $classes ) {
	// Adds a class of group-blog to blogs with more than 1 published author.
	if ( is_multi_author() ) {
		$classes[] = 'group-blog';
	}

	return $classes;
}
add_filter( 'body_class', 'body_classes' );

Las siguientes son algunas referencias para formatear la documentación en línea con las mejores prácticas en PHP, JavaScript y CSS:

Si está utilizando SublimeText, le sugiero que instale DocBlockr, que inteligentemente rellenará previamente su código con documentación en línea.

Estándares de codificación para WordPress [Guide]

Estándares de codificación para WordPress [Guide]

La razón por la que tenemos estándares de codificación (no solo para WordPress) es crear un familiar … Leer más

3. Elementos gráficos

Usa elementos gráficos, hablan mejor que el texto. Estos medios resultan útiles, especialmente si crea software con interfaz gráfica. Puede agregar elementos señaladores como flechas, círculo o cualquier cosa que pueda ayudar a los usuarios a averiguar adónde ir para realizar los pasos, sin conjeturas.

El siguiente es un ejemplo de la aplicación Tower en el que puede inspirarse. Explican de manera eficiente cómo funciona el control de versiones de una manera agradable que lo hace más comprensible que usar líneas de comando de texto sin formato.

4. Seccionamiento

Puede considerar incluir algunas cosas en la documentación en listas y tablas con viñetas, ya que esto hace que el contenido más extenso sea más fácil de escanear y leer para los usuarios.

Agregue una tabla de contenido y divida la documentación en secciones fácilmente digeribles, pero manteniendo cada sección relevante con lo que viene a continuación. Sea breve y sencillo. A continuación se muestra un ejemplo de documentación bien organizada en Facebook. La tabla de contenido nos lleva a donde queremos ir con un clic.

ejemplo de doc facebook
5. Revisar y actualizar

Por último, revise la documentación en busca de errores y revísela cuando sea necesario o cuando haya cambios significativos en el producto, el software o la biblioteca. Su documentación no sería de utilidad para nadie si no se actualiza regularmente junto con su producto.