Desarrolladores Por qué no deberías omitir la documentación

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

A diferencia del código de escritura (que es lo que los desarrolladores inscribieron para hacer), la documentación (que no lo hicimos) debe y 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.

Si bien puede ser una verdadera carga, escribir la documentación es importante y ofrecerá ventajas para sus usuarios, colegas y, especialmente, para usted mismo..

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 suponer que los usuarios del software serán competentes. Por lo tanto, la documentación puede ser material fino, omitiendo muchos de los elementos esenciales que debería haber contenido desde el principio. Si usted es experto en el idioma, puede resolver las cosas por su propia iniciativa; Si no estás, entonces estás perdido..

La documentación destinada a los usuarios suele consistir en el uso práctico o la “cómo”. La regla de oro al crear documentación para usuarios generales es que debe ser claro. Usar palabras amigables con los humanos es preferible a los términos técnicos o la jerga. Ejemplos de uso real también serán muy apreciados..

Un buen diseño de diseño también ayudaría a los usuarios a escanear cada sección de la documentación sin esfuerzo 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 también

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 los otros compañeros de equipo. Por eso es esencial tener un consenso sobre una norma para mantener a todos en la misma página. Una documentación debidamente escrita sería la referencia que necesita el equipo.

Pero a diferencia de la documentación del usuario final, esta documentación describe típicamente procedimientos tecnicos como la convención de nomenclatura de códigos, que muestra cómo se deben construir las 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 tengas nuevos miembros que se unen Más tarde, su equipo, esta documentación podría ser una manera eficaz de capacitarlos, por lo que no tiene que darles una explicación de 1 a 1 sobre el código..

Extrañamente también ayuda al 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 mantenido intactos durante meses o incluso años..

La repentina necesidad de volver a visitar los códigos por una razón u otra lo dejaría a uno preguntándose qué pasaba por sus mentes cuando escribieron estos códigos. No te sorprendas: he estado en esta situación antes.. Esto es precisamente cuando yo deseado Yo 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 ahorrará una gran cantidad de tiempo que puede dedicar a obtener los cambios en.

Lo que hace para una buena documentación?

Hay varios factores que para construir una buena pieza de documentación..

1. Nunca asumas

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

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

La conclusión es que la documentación está escrita con el proceso mental de un usuario, no 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. Siga el estándar

Al añadir documentación que va en línea con el código., Utiliza 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.

 / ** * Agrega clases personalizadas a la matriz de clases de cuerpo. * * @param array $ classes Clases para el elemento body. * @return array * / function body_classes ($ classes) // Agrega una clase de grupo-blog a blogs con más de 1 autor publicado. if (is_multi_author ()) $ classes [] = 'group-blog';  devolver $ clases;  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:

• PHP: PHP Documentation Standard para WordPress
• JavaScript: UseJSDoc
• CSS: CSSDoc

Si está utilizando SublimeText, sugeriría instalar DocBlockr que rellenará su código de manera inteligente con la documentación en línea..

3. Elementos gráficos.

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

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

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 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 de fácil digestión, pero manteniendo cada sección relevante con lo que sigue. Mantenlo corto y directo. A continuación se muestra un ejemplo de documentación muy bien organizada en Facebook. La tabla de contenido nos lleva a donde queremos saltar en un clic.

5. Revisar y actualizar

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