La importancia de la documentación para los desarrolladores web

Al desarrollar aplicaciones móviles, web y de escritorio o bibliotecas de JavaScript, la documentación juega un papel importante para determinar el éxito de una aplicación. Pero si alguna vez ha hecho documentación, estará de acuerdo conmigo en que esto es lo último que les gusta hacer a los desarrolladores.

A diferencia de escribir código, que es un trabajo firmado por los desarrolladores, la documentación debe ser fácil de entender. todosTécnicamente, necesitamos traducir el lenguaje de máquina (código) a un lenguaje legible por humanos, que es más difícil de lo que parece.

Si bien esto puede ser una verdadera carga, escribir documentación es importante y beneficiará a sus usuarios, a sus colegas y especialmente a usted mismo.

Una buena documentación ayuda a los usuarios

La documentación ayuda a los lectores Descubra cómo funciona el códigoobviamente. Pero muchos desarrolladores asumen erróneamente que los usuarios de software tendrán experiencia.

Como resultado, la documentación puede ser escasa y omitir muchos puntos que deberían haberse incluido desde el principio. Si conoce el idioma, puede resolver problemas de manera proactiva; si no lo eres, estás perdido.

La documentación centrada en el usuario a menudo incluye el uso real o "cómo hacerlo". La regla básica al crear documentación para usuarios comunes es debe quedar claroEl uso de palabras amigables para los humanos es preferible a los términos técnicos o la jerga. También se apreciarán ejemplos prácticos de uso.

Un buen diseño de diseño también puede ayudar a los usuarios a navegar por cada parte de un documento sin fatiga visual. Algunos buenos ejemplos (también conocidos como mis favoritos) son gestor de arranque y WordPress"Los primeros pasos a WordPress".

ayuda a otros desarrolladores

Cada desarrollador tiene su propio estilo de codificación. Sin embargo, cuando se trata de trabajo en equipo, a menudo tenemos que compartir código con otros compañeros de equipo. por lo que es necesaria De acuerdo con las normas Haz que todos estén en la misma página. La documentación debidamente redactada será la referencia que necesita el equipo

Sin embargo, a diferencia de la documentación del usuario final, esta documentación generalmente describe procedimiento técnico Al igual que las convenciones de nomenclatura de código, le muestra cómo crear una página específica y cómo funciona la API con código de muestra. A menudo también tenemos que escribir documentación dentro del código (llamada Comentario) para describir lo que hace el código.

Además, si tienes unirse a un nuevo miembro Más tarde, esta documentación puede ser una forma efectiva y que ahorra tiempo de capacitar a su equipo para que no tenga que hacer pruebas de código individuales con ellos.

También ayuda a los propios codificadores.

Lo curioso de la codificación es que a veces Incluso los propios desarrolladores no entienden el código que están escribiendo.Esto es especialmente cierto cuando el código no se ha tocado durante meses o incluso años.

La repentina necesidad de revisar el código por alguna razón hace que las personas se pregunten qué estaba pasando en sus cabezas cuando lo escribieron. No te sorprendas: esto me ha pasado antes. Está exactamente Cuando yo esperanza He documentado mi código correctamente..

Al documentar su código, podrá hacerse una idea de su código rápidamente y sin decepciones, ahorrándole mucho tiempo para realizar cambios.

¿Qué es una buena documentación?

Hay varios factores que contribuyen a construir una buena documentación. Algunas de las más importantes son las siguientes:

1. Nunca adivines

No asuma que sus usuarios saben nada Ustedes lo que sabes ellos Me pregunto. siempre es mejor Empezar desde el principio Independientemente del nivel de competencia del usuario.

Por ejemplo, si ha creado el complemento jQuery, puede comenzar con SlickJSdocumentación de. Muestra cómo crear HTML, dónde colocar CSS y JavaScript, cómo inicializar el complemento jQuery en el nivel más básico e incluso muestra el marcado final completo después de agregar todas estas cosas, lo cual es obvio.

Lo que es más importante, la documentación está escrita en función del proceso de pensamiento del usuario, no del desarrollador. Trabajar con sus propios documentos de esta manera le dará una mejor perspectiva sobre cómo organizar su propio trabajo.

2. Sigue los estándares

Cuando agrega documentación incrustada con código, Estándares esperados para el uso del lenguajeSiempre es una buena idea describir cada función, variable y valor que devuelve la función. Aquí hay un buen ejemplo de documentación incrustada de 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' );

Aquí hay algunos enlaces para formatear documentos incrustados utilizando las mejores prácticas en PHP, JavaScript y CSS:

Si usa SublimeText, le recomiendo instalar interceptor de documentos Esto ajustará su código de antemano con la documentación integrada.

3. Elementos gráficos

Utiliza elementos gráficos, hablan mejor que las palabras. Estos medios son útiles, especialmente si está creando software GUI. Puede agregar elementos señaladores como flechas, círculos o Cualquier cosa que ayude al usuario a averiguar dónde ir para realizar estos pasos sin conjeturas.

Aquí hay un ejemplo de la aplicación Tower, en el que puede inspirarse. Explican efectivamente cómo funciona el control de versiones de una manera agradable que lo hace más fácil de entender que usar una línea de comando de texto sin formato.

4. Rebanar

Es posible que desee considerar incluir parte del contenido de su documento en tablas de clasificación y tablas, ya que esto hace que el contenido más extenso sea más fácil de escanear y leer para los usuarios.

Agregue contenido y divida la documentación en secciones fáciles de entender, manteniendo cada sección relevante para lo que sigue. ser breve y al granoEl siguiente es un ejemplo de un documento bien organizado. FacebookEl contenido nos lleva a donde queremos hacer clic.

5. Modificaciones y actualizaciones

Finalmente, revise la documentación en busca de errores y revísela si es necesario o cuando haya cambios importantes en el producto, el software o la biblioteca. Su documentación será inútil para cualquier persona sin actualizaciones periódicas junto con su producto.