fbpx

¿Cómo hacer tu documentación para tu proyecto de JavaScript?

Seguramente te encontrás en la búsqueda de una nueva oportunidad laboral, una compañía IT que realmente te valore. Y tal vez sentís que eres capaz de asumir proyectos importantes por tu experiencia adquirida en JavaScript, ¿cierto? Si es así, podrías estar en lo correcto.

Pero vos sabrás también que nadie considerará tu proyecto JavaScript sin la documentación debida. Como desarrollador web, nunca construyes algo desde cero, sabés que debés utilizar diversas bibliotecas integradas. Si, por ejemplo, diseñás una aplicación, requerirás de 6 o 7 bibliotecas principales.

Utilizarías frameworks para front-end, back end, drivers para manejo de base de datos, etc., desde React, Express, GraphQL, Jest, Mocha, Bootstrap o Node.js ¿Ya sabés cómo aprender todas estas herramientas? Con la documentación, ¿y vos sabés hacerla? Acá te explicamos cómo.

Rol de CTO

¿Por qué es vital hacer documentación para tu proyecto?

Cualquier empresa de desarrollo de software deseará contar con una biblioteca bien documentada. Y ningún CEO o CTO arriesgará sus recursos en tecnología con tiempos de incorporación impredecibles. He allí la importancia de la documentación para tu proyecto JavaScript.

 

Otro factor negativo, que deriva de no contar con la documentación, es el hecho de no entender tus propios códigos. El objetivo primordial de la documentación es explicar la razón por la cual escribiste determinado software. Esta información es esencial, incluso para vos a futuro.

Imaginá que escribís un código hace mucho tiempo, pero olvidaste su documentación. Como sabés, estos escritos van de la mano con el código ya que facilitan su lectura. Este tipo de errores resulta fatal para el programador y para la empresa tecnológica que lo contrate.

Además, tendrías que pensar mucho sobre el diseño de tu código cuando desees documentarlo. Desde que expongas la estructura entera del código al público, deberás pensar la forma de construir el proyecto JavaScript.

Es importante hacer documentación JavaScript

Photo by Artem Sapegin on Unsplash. Licencia CC0

 

El proceso de documentación en sí, puede mejorar el código. Te invita a cuestionarte ¿existen maneras de implementar mejores funciones? ¿es posible reorganizar completamente el código?

Herramientas que necesitás para tu documentación de JavaScript

Para optimizar la creación de tu proyecto JavaScript podés usar diversas herramientas accesibles de documentación que te aportarán velocidad. Conocé estas herramientas y generá tu documentación con un excelente código y comentarios online en un solo comando.

  • Docusaurus

Docusaurus es una herramienta funcional que te permitirá generar la documentación entera de tu sitio web. Está basado en React y admite control de versiones, además, posee búsqueda integrada y compatibilidad multilenguaje.

Con Docusaurus podrás contar con diferentes versiones de la documentación generada anteriormente. Esta compleja pero excelente herramienta se basa en archivos de markdown con contenido de documentación.

  • JSDoc

Si buscás el generador de documentación JavaScript más popular, acá lo tenés. JSDoc es una herramienta súper útil y simple, solo debés ejecutar el comando jsdoc con un nombre de archivo como argumento ¡Listo! Se generará un archivo HTML con documentación para usar.

  • apiDoc

Esta es una buena herramienta para generar la documentación de tu proyecto, si este posee y expone métodos API. apiDoc crea la documentación a partir de anotaciones API en el código fuente. Podés personalizar, especificar parámetros, códigos de error, etc.

 

Herramientas para documentación JavaScript

Foto de Markus Spiske temporausch.com en Pexels. Licencia CC0

Decidí qué escribir

Ahora que ya entendés la importancia de la documentación, conocés las mejores herramientas y querés arrancar ¿Qué sigue? Factores importantes antes de decidirte sobre qué escribir.

  • Definir tu público objetivamente: Este detalle es esencial, ya que te ayudará a enfocar tus esfuerzos de mejor manera. Debés saber para quién se está escribiendo, qué tipo de usuarios componen la audiencia y qué buscan.
  • El nombre de tu proyecto y a qué tipo de problema va dirigido: Evita descripciones muy largas o vagas, usá una o dos oraciones. Recordá que muchos visitarán la página y debés ser lo más preciso posible.

Solo debés enfocarte en que, tanto en el título como descripción, se indique de qué trata el proyecto JavaScript. También se debe indicar a quién está dirigido y el problema que soluciona.

  • Velocidad: Procurá que el inicio sea rápido, los pasos de instalación deberían estar expuestos en una lista breve.
  • La documentación de componentes: Enumerá esas partes del software que requieran documentación, de haberlas. Colocá nombre del componente, uso, proceso de instalación, etc.
  • Licencia: Existen licencias estándar accesibles que podés utilizar en tu proyecto JavaScript, decidí la mejor. Elegí en qué condiciones se distribuirá y podrá utilizar el software. Tenés a la mano MIT, Apache GNU o BSD, las cuales son de código abierto y muy funcionales.

Ahora bien, ¿sobre qué escribir? Prestá atención a estos excelentes consejos que traemos para ti.

  • Verificá tu propio código ejecutándolo, ya que todos lo copiarán y pegarán. No coloqués caracteres invisibles para codificar ejemplos. Usá etiquetas de código y blockquote para incrustar bloques de código.
  • Recordá que los comentarios de código son parte importante de la documentación. Con JSDoc generarás documentación basada en comentarios. Alimentá la herramienta con la base de código y listo.
  • Actualizá la documentación, si realizás un cambio en el código, debés hacerlo también en tu documentación.

¿Buscás trabajo en Argentina?

Recordá que la documentación es esencial para el éxito de un proyecto JavaScript. Actualizálo y ponete en el lugar de tus usuarios. Si actualmente estás buscando un empleo de calidad que te brinde la oportunidad de desarrollarte, tomá una decisión ya.

En Argentina existen muchas empresas de desarrollo de software, pero mirá bien las opciones a tu alcance. Iniciá hoy tu capacitación y poné todo tu empeño en mejorar, esto será clave en tu contratación.

Rol de CTO

Conclusión

Actualmente, toda empresa IT posee expectativas altas y requiere el mejor equipo tecnológico. Este componente humano le aportará las herramientas para hacer frente a cualquier cliente y sus exigencias.

En G&L Group trabajamos diariamente para ofrecer lo máximo en rendimiento y operatividad. Nuestros servicios incluyen el desarrollo, infraestructura, GRC, seguridad y presentación, I+D+I, entre otros.

Poseemos más de 20 años de trayectoria tecnológica, brindando calidad y soluciones a múltiples compañías. Abarcamos las áreas de banca y finanzas, retail, salud, etc.

G&L Group cuenta con un staff capacitado y en constante crecimiento humano y tecnológico, siempre a la vanguardia.

 

Si vos apreciaste este artículo, podrías leer estos:

Conocé lo más actual en tecnología del 2019

¿Le brindás a tus clientes el cifrado de doble vía?

Las tendencias en métodos de seguridad