La documentación es de suma importancia en cualquier aplicación móvil, librería de JavaScript y framework CSS o HTML. Tal vez no lo creas, pero la documentación también tiene impacto en el éxito de una aplicación, así como la respuesta por parte del público.
Sin embargo, es probable que la documentación se tu parte menos favorita del proceso de desarrollo, aunque sí es muy necesaria. Ya que la documentación debe ser entendida por un número más amplio de personas y no sólo por ti, entonces deberás comenzar a ponerte en la perspectiva de tus usuarios y emplear términos no técnicos. Puede ser complicado al principio por ello te traemos una serie de pautas para que puedas crear una buena documentación. Pero antes listaremos las tres principales razones por las cuales se considera que la documentación es esencial en cualquier proyecto de desarrollo web.
Importancia de la documentación
Si es que aún te parece que la documentación no es necesaria, te listamos tres ventajas de aprender a redactarla e incluirla en tus proyectos:
Una buena documentación ayuda a los usuarios
La documentación ayuda a los usuario a entender cómo funciona el código. Hay que tener en cuenta que muchos de ellos no tienen conocimiento sobre lenguajes de programación y sólo esperan ver resultados al instalar cierto plugin o aplicación. Por esta razón, la documentación debe incluir desde lo más esencial. Lo importante es no asumir que el usuario conoce sobre algún tema, particularmente si tu aplicación o plugin se encuentra en algún mercado en línea como CodeCanyon.
Ya que la documentación ayuda a tus usuarios a entender el uso práctico de tu aplicación y es probable que la mayoría no tenga conocimientos sobre programación, deberás evitar las palabras técnicas e intentar explicar todo de manera más práctica. Los ejemplos de uso o configuración serán grandemente apreciados por tus usuarios, así que si tienes la oportunidad de incluirlos te recomendamos que lo hagas.
La buena estructura y organización de tu documentación también es favorable para los usuarios pues de esa manera los usuarios pueden encontrar el tema que más les interesa de momento.
Una buena documentación ayuda a otros desarrolladores
Cada desarrollador tiene su propia forma de trabajo, pero cuando se trabaja en equipo es probable que el código no sea propiedad de un solo desarrollador y se tenga que enviar partes del mismo a otros miembros de equipo. En esta ocasiones es importante tener un acuerdo sobre los estándares del código, de esta manera se agilice el proceso pues todos los desarrolladores están informados sobre el estándar empleado. Es aquí donde la documentación entra en juego y cumple un papel esencial en equipos de desarrolladores pues sirve como material de referencia.
Esta documentación, al ser dirigida a desarrolladores y no usuarios finales, debe contener la descripción de los procedimientos técnicos. De modo que puedes incluir términos propios del lenguaje y palabras técnicas. El uso de ejemplos sobre el funcionamiento del código también es bienvenido. Adicionalmente a una buena documentación, puedes incluir comentarios que describan lo que hace el código dentro de su propio archivo.
Una buena documentación ayuda al propio desarrollador del proyecto
Al crear una buena documentación de tu aplicación o plugin, serás capaz de comprender mejor el funcionamiento de tu código pues tendrás que explicarlo para otros desarrolladores o usuarios. Asimismo, aprenderás a trabajar de manera más ordenada con tu código, práctica que será bastante útil en el futuro.
Otra situación en la que una documentación ayuda al desarrollador encargado del proyecto es cuando dejan por un buen tiempo de trabajar en cierto código y, tiempo después, cuando regresan al proyecto pueden entender más fácilmente su código gracias a la documentación. Mientras más tiempo hayas pasado sin trabajar en ese código, más útil te será la documentación.
¿Cómo crear una buena documentación?
Ahora que hemos establecido las ventajas principales que puedes obtener al crear una buena documentación y entiendes la importancia de la misma, te daremos algunas pautas paras poder crear una buena documentación de tu código:
No asumas que el usuario tiene los mismos conocimientos que tú posees
No asumas que tus usuarios tienen el mismo nivel de conocimiento que tú. Es genial si se da esa situación, pero es mucho mejor empezar siempre desde lo más básico de manera que cualquier usuario, sin importar su nivel de conocimiento puede entenderlo.
Es esencial que tengas en cuenta para quién estás redactando esta documentación y te pongas en el lugar de tus usuarios. Ver desde la perspectiva del usuario puede ser complicado, así que tener en tus manos un perfil de usuario podría ser de utilidad para ayudar con esta tarea. Una vez que tengas en claro cuál es la perspectiva del usuario podrás organizar mucho mejor tu documentación.
Sigue los estándares de cada lenguaje
Si bien es cierto que cada desarrollador tiene un método de trabajo distinto, para la documentación y, en particular, para los comentarios dentro del código, es provechoso tener en cuenta el estándar para cada lenguaje. También es una buena idea describir cada función, las variables y los valores que regresa esa función. Para ello es esencial que tu código esté lo más ordenado posible. Esta situación será favorable no sólo para otros desarrolladores, sino también para ti pues te permitirá tener una base sobre la cuál empezar a estructurar tu documentación. En otras palabras, un código ordenado y con comentarios adecuados te ayudará a ahorrar tiempo en otras fases el proceso como es la documentación.
Incluye elementos gráficos
Añadir elementos como flechas ayudará al usuario a comprender más fácilmente los pasos que deben lograrse para realizar ciertas funciones. También puedes incluir los pasos en una lista numerada, aunque podría ser complicado pues deberás combinar explicaciones con los pasos a tomar. Lo esencial de toda lista numerada es que los pasos sean explicados de manera concisa. Incluir grandes bloques de texto le hará pensar a los usuarios que es realmente complicado usar tu aplicación y podrían perder el hilo de la explicación si no se va al punto directamente.
Otra alternativa a usar flechas para detallar los pasos a seguir puede ser primero incluir la explicación sobre la función y posteriormente la lista de los pasos a seguir. De esta manera, el contenido se mantiene más ordenado.
Añade un índice
El uso de listas numeradas o con viñetas, así como las tablas puede ser de ayuda para los usuarios al momento de leer y estudiar la documentación, así que te animamos a incluirlos cada vez que sea posible. Asimismo, deberás añadir una tabla de contenidos con los enlaces respectivos en cada sección. Este índice ayudará a los usuarios a localizar información de manera más rápida y sencilla, de modo que no importa cuántas veces recurran a la documentación, siempre podrán encontrar la información que buscaban.
Actualiza tu documentación
Por último, es esencial actualizar el contenido de tu documentación cada vez que realices algún cambio en el código de tu aplicación, ya sea para mejorar las características de la misma o para solucionar errores. Estos cambios deberán ser plasmados en la documentación.
0 Comentarios