sábado, octubre 24, 2020

Documentando (0): Algunas ideas previas

Existen muchos artículos y libros que enseñan a documentar el código, e incluso estándares que intentan poner un poco de orden en cómo se tiene que documentar un proyecto de ingeniería. Esta serie del blog no intenta hacer un nuevo estándar o ser una referencia para los demás. Simplemente sirve para ordenar mis propias ideas de cómo lo tendría yo que hacer... Lo único que en vez de guardarlo para mí sólo (como hasta ahora lo estaba haciendo hasta ahora) he decidido exponerlo de forma pública a ver si a alguien más le puede interesar o aportar alguna idea.

Me voy a centrar principalmente las siguientes partes de la generación de un proyecto de electrónica:
  1. Programación del firmware. Aquí se va a utilizar principalmente C
  2. Esquemas (planos)
  3. Documentación de fabricación. Además de los gerbers y el BOM de una PCB yo entrego una serie de documentación adicional.
Las herramientas que utilizo para generar la documentación son:
  • Doxygen (https://www.doxygen.nl/). Para generar la documentación a partir de comentarios en el código. Es fácil de aprender a usar y, si te quieres meter a fondo, tiene un montón de posibilidades. 
  • PlantUML (http://www.plantuml.com/). Se integra muy bien con Doxygen y permite hacer un montón de tipos de diagramas UML simplemente describiéndolos en el texto.
  • Dia (https://wiki.gnome.org/Apps/Dia). Cuando no pueda o no quiera describir un diagrama con PlantUML los dibujaré con esta aplicación.
  • Libre Office (https://es.libreoffice.org/). Algunos documentos tienen que ser escritos a mano así que...
La mayor parte de la documentación se realiza sobre el documento de trabajo (ya sea el código, los esquemas o la PCB) así que además pondré las formas que utiliza para documentar.

También iré añadiendo algunas otras cosas como el control de versiones y organización de los documentos que se generan.

No hay comentarios: