La importancia de la documentación para desarrolladores web

En el ámbito del desarrollo de aplicaciones móviles, web y de escritorio o bibliotecas JavaScript, la documentación juega un papel importante en la determinación del éxito de la aplicación. Pero si alguna vez ha realizado documentación, estará de acuerdo conmigo en que es lo que menos les gusta hacer a los desarrolladores.

A diferencia de escribir código (que es lo que los desarrolladores se inscribieron para hacer), la documentación debe ser fácilmente digerida por todo el mundo. 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 verdadera carga, escribir la documentación es importante y brindará 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 muchas ideas falsas y mitos que rodean el arte de la programación. Muchos lo ven como un trabajo … Lee mas

La buena documentación ayuda a los usuarios

La documentación ayuda al lector. entender cómo funciona un códigoobviamente. Pero muchos desarrolladores cometen el error de suponer que los usuarios del software serán competentes. Por lo tanto, la documentación puede ser material delgado, omitiendo 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 eres, entonces estás perdido.

La documentación destinada a los usuarios generalmente consiste en un uso práctico o el "cómo hacerlo". La regla general al crear documentación para usuarios generales es que debe ser claro. Usar palabras amigables para los humanos es preferible a los 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 realmente ayudaría 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 documentación para Bootstrap y WordPress ‘“ Primeros pasos con 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 esencial tener un consenso sobre un estándar para mantener a todos en la misma página. Una documentación debidamente escrita 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 está haciendo el código.

Además, en el caso de que tenga nuevos miembros se unen más tarde para su equipo, esta documentación podría ser una forma efectiva en tiempo de entrenarlos, por lo que no tiene que darles un descuido 1 a 1 en el código.

10 hábitos de programación que los desarrolladores deberían adoptar

10 hábitos de programación que los desarrolladores deberían adoptar

Estos resultados pueden reducir nuestra confianza pero, de hecho, se pueden resolver con prácticas de desarrollo adecuadas … Lee mas

También ayuda al codificador mismo

Lo curioso de la codificación es que a veces incluso los desarrolladores mismos 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.

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

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

¿Qué hace para una buena documentación?

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

1. Nunca asumas

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

Si creó un complemento jQuery, por ejemplo, puede inspirarse en la documentación de SlickJS. Muestra cómo estructurar el HTML, dónde colocar el CSS y el 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 todo esto, lo cual es algo obvio.

doc ejemplos

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 en la organización de su propia pieza.

2. Sigue el estándar

Al agregar documentación que va en línea con el código, usar el estándar esperado del idioma. Siempre es una buena idea describir cada función, las variables y 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 completará su código de forma inteligente con la documentación en línea.

Estándares de codificación para WordPress (Guía)

Estándares de codificación para WordPress (Guía)

La razón por la que tenemos estándares de codificación (no solo para WordPress) es para crear un … Lee mas

3. Elementos gráficos.

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

El siguiente es un ejemplo de la aplicación de la Torre donde puedes inspirarte. Explican eficientemente 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.

(incrustar) https://www.youtube.com/watch?v=e8PGuOyZ3YU (/ incrustar)

4. Seccionamiento

Puede considerar incluir algunas cosas en la documentación dentro de listas y tablas con viñetas, ya que esto hace que el contenido más largo 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, manteniendo cada sección relevante con lo que viene a continuación. Mantenlo corto y directo. A continuación se muestra un ejemplo de documentación bien organizada en Facebook. La tabla de contenido nos lleva a donde queremos saltar con un clic.

doc ejemplo facebook
5. Revisar y actualizar

Por último, revise la documentación en busca de errores y corríjala 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.

Deja un comentario

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *