{"id":555,"date":"2026-07-22T08:17:36","date_gmt":"2026-07-22T08:17:36","guid":{"rendered":"https:\/\/matforge.org\/?p=555","raw":"https:\/\/matforge.org\/?p=555"},"modified":"2026-07-22T08:17:36","modified_gmt":"2026-07-22T08:17:36","slug":"research-software-documentation-practical-guide-scientists","status":"publish","type":"post","link":"https:\/\/matforge.org\/es\/research-software-documentation-practical-guide-scientists\/","title":{"rendered":"Documentaci\u00f3n de software de investigaci\u00f3n: una gu\u00eda pr\u00e1ctica para cient\u00edficos","raw":"Documentaci\u00f3n de software de investigaci\u00f3n: una gu\u00eda pr\u00e1ctica para cient\u00edficos"},"content":{"rendered":"<span class=\"span-reading-time rt-reading-time\" style=\"display: block;\"><span class=\"rt-label rt-prefix\">Reading Time: <\/span> <span class=\"rt-time\"> 9<\/span> <span class=\"rt-label rt-postfix\">minutes<\/span><\/span><p>Acabas de terminar una canalizaci\u00f3n de simulaci\u00f3n. Sus resultados est\u00e1n listos para la publicaci\u00f3n. Su c\u00f3digo funciona. Entonces, \u00bfpor qu\u00e9 todav\u00eda necesita documentarlo?<\/p>\n<p>Porque sin documentaci\u00f3n, su software es m\u00e1s dif\u00edcil de citar, m\u00e1s dif\u00edcil de reproducir y m\u00e1s dif\u00edcil de mantener. Es posible que los colaboradores no entiendan c\u00f3mo ejecutarlo. Es posible que los futuros estudiantes no sepan qu\u00e9 archivo de configuraci\u00f3n importa. Incluso puede olvidar las decisiones clave de dise\u00f1o despu\u00e9s de varios meses.<\/p>\n<p>La documentaci\u00f3n no es un complemento agradable para el software de investigaci\u00f3n. Es el puente entre una herramienta de trabajo y un activo de investigaci\u00f3n reproducible. No necesitas ser un escritor t\u00e9cnico para hacerlo bien. Necesitas una estructura.<\/p>\n<h2>Comida clave<\/h2>\n<ul>\n<li>La documentaci\u00f3n forma parte de la investigaci\u00f3n reproducible. El c\u00f3digo sin documentaci\u00f3n se convierte en una caja negra que solo su autor original puede mantener.<\/li>\n<li>Cuatro tipos de documentaci\u00f3n sirven a cuatro necesidades de los usuarios diferentes: tutoriales para el aprendizaje, gu\u00edas pr\u00e1cticas para hacer, referencia para describir y explicaci\u00f3n para la comprensi\u00f3n.<\/li>\n<li>El marco de Di\u00e1taxis es una forma pr\u00e1ctica de organizar la documentaci\u00f3n de software de investigaci\u00f3n.<\/li>\n<li>Las diez reglas simples para documentar software cient\u00edfico proporcionan una lista de verificaci\u00f3n \u00fatil para escribir una mejor documentaci\u00f3n.<\/li>\n<li>Ya existen plantillas y herramientas. Readme Structures, <code>CITATION.cff<\/code> archivos, Sphinx, MKDOC y Read Los documentos hacen que el proceso sea m\u00e1s eficiente.<\/li>\n<\/ul>\n<h2>Por qu\u00e9 importa la documentaci\u00f3n<\/h2>\n<p>El software de investigaci\u00f3n se encuentra entre la ciencia y la ingenier\u00eda. A diferencia del equipo de laboratorio tradicional, el software puede ser compartido, modificado, reutilizado y citado por cualquier persona con el entorno adecuado. Pero ese potencial significa poco si nadie entiende c\u00f3mo funciona el software.<\/p>\n<p>Las apuestas son pr\u00e1cticas:<\/p>\n<ul>\n<li>reproducibilidad. Sin documentaci\u00f3n, otros investigadores no pueden verificar o reutilizar su trabajo de manera confiable.<\/li>\n<li>cita Es menos probable que el software que carece de gu\u00edas de citas e instrucciones de uso reciba el cr\u00e9dito adecuado.<\/li>\n<li>mantenimiento. Cuando un investigador deja un laboratorio, el c\u00f3digo indocumentado a menudo se convierte en deuda t\u00e9cnica para la siguiente persona.<\/li>\n<\/ul>\n<p>Una buena documentaci\u00f3n hace que el software sea m\u00e1s f\u00e1cil de usar, ampliar, revisar y conservar. Tambi\u00e9n reduce el n\u00famero de preguntas repetidas de colaboradores y futuros usuarios.<\/p>\n<p>Esta gu\u00eda le brinda un marco pr\u00e1ctico y plantillas para documentar el software de investigaci\u00f3n de manera efectiva.<\/p>\n<h2>El marco de la Di\u00e1taxis: cuatro tipos de documentaci\u00f3n<\/h2>\n<p>Si su documentaci\u00f3n vive actualmente en un archivo L\u00e9ame largo, puede parecer desorganizado. Los tutoriales, las notas de instalaci\u00f3n, los detalles de la API, la teor\u00eda, los ejemplos y la soluci\u00f3n de problemas pueden mezclarse f\u00e1cilmente.<\/p>\n<p>El marco de Di\u00e1taxis resuelve esto separando la documentaci\u00f3n en cuatro tipos distintos. Cada tipo sirve a una necesidad de usuario diferente.<\/p>\n<h3>1. Tutoriales<\/h3>\n<p>Un tutorial est\u00e1 orientado al aprendizaje. Lleva a un principiante a trav\u00e9s de un camino guiado y lo ayuda a lograr un resultado concreto.<\/p>\n<p>Ejemplo: \u201cConfigurar Fipy para su primera simulaci\u00f3n de campo de fase\u201d.<\/p>\n<p>Un tutorial Respuestas: \u00bfC\u00f3mo aprendo a usar este software?<\/p>\n<h3>2. Gu\u00edas pr\u00e1cticas<\/h3>\n<p>Una gu\u00eda pr\u00e1ctica est\u00e1 orientada a la acci\u00f3n. Ayuda a alguien a completar una tarea espec\u00edfica despu\u00e9s de que ya entiende los conceptos b\u00e1sicos.<\/p>\n<p>Los ejemplos incluyen:<\/p>\n<ul>\n<li>C\u00f3mo ejecutar una simulaci\u00f3n de Monte Carlo con Fipy.<\/li>\n<li>C\u00f3mo solucionar errores de convergencia.<\/li>\n<li>C\u00f3mo exportar los resultados de la simulaci\u00f3n a CSV.<\/li>\n<\/ul>\n<p>Respuestas de una gu\u00eda de instrucciones: \u00bfC\u00f3mo logro una tarea espec\u00edfica?<\/p>\n<h3>3. Referencia<\/h3>\n<p>La documentaci\u00f3n de referencia est\u00e1 orientada a la informaci\u00f3n. Es factual, neutral y completo. Describe lo que proporciona el software sin ense\u00f1ar o persuadir.<\/p>\n<p>Los ejemplos incluyen:<\/p>\n<ul>\n<li>Documentaci\u00f3n de API.<\/li>\n<li>Firmas de funci\u00f3n.<\/li>\n<li>Especificaciones de los par\u00e1metros.<\/li>\n<li>Definiciones de clase.<\/li>\n<\/ul>\n<p>Documentaci\u00f3n de referencia Respuestas: \u00bfQu\u00e9 hace esto?<\/p>\n<h3>4. Explicaci\u00f3n<\/h3>\n<p>La explicaci\u00f3n est\u00e1 orientada a la comprensi\u00f3n. Proporciona antecedentes, contexto, razonamiento y fundamento de dise\u00f1o.<\/p>\n<p>Los ejemplos incluyen:<\/p>\n<ul>\n<li>Por qu\u00e9 el solucionador utiliza un paso de tiempo impl\u00edcito.<\/li>\n<li>El modelo matem\u00e1tico detr\u00e1s de la implementaci\u00f3n.<\/li>\n<li>Por qu\u00e9 se eligi\u00f3 una estrategia de malla sobre otra.<\/li>\n<\/ul>\n<p>Explicaci\u00f3n Respuestas: \u00bfPor qu\u00e9 esto funciona de esta manera?<\/p>\n<h2>Las diez reglas simples para documentar software de investigaci\u00f3n<\/h2>\n<p>Las diez reglas simples para documentar el software cient\u00edfico son una lista de verificaci\u00f3n pr\u00e1ctica para la calidad de la documentaci\u00f3n. Son \u00fatiles porque se enfocan en los h\u00e1bitos que los investigadores pueden aplicar sin construir un departamento de documentaci\u00f3n completo.<\/p>\n<h3>Regla 1: Escribe comentarios mientras codificas<\/h3>\n<p>Los comentarios deben explicar las ideas y el razonamiento detr\u00e1s del algoritmo, no simplemente repetir lo que el c\u00f3digo ya dice.<\/p>\n<pre><code class=\"language-python\"># Good: explains why this approach is used\n# Use implicit time stepping for stiff reaction terms to avoid\n# timestep restrictions that would make the simulation impractical.\nsolver = ImplicitTimeStepping(reaction_terms)\n\n# Bad: repeats the line without explaining intent\nsolver = ImplicitTimeStepping(reaction_terms)  # creates solver\n<\/code><\/pre>\n<h3>Regla 2: Incluya muchos ejemplos<\/h3>\n<p>Los ejemplos muestran a los usuarios c\u00f3mo funciona el software en la pr\u00e1ctica. Proporcione ejemplos ejecutables que demuestren el flujo de trabajo principal.<\/p>\n<p>Si la documentaci\u00f3n est\u00e1 demasiado llena de ejemplos, mu\u00e9valos a un directorio <code>examples\/<\/code> dedicado y vinc\u00falelos desde la documentaci\u00f3n principal.<\/p>\n<h3>Regla 3: Incluya una gu\u00eda de inicio r\u00e1pido<\/h3>\n<p>Una gu\u00eda de inicio r\u00e1pido deber\u00eda permitir que alguien use el software a los pocos minutos de descargarlo. Debe incluir la instalaci\u00f3n, un ejemplo m\u00ednimo y la salida esperada.<\/p>\n<p>Sin un inicio r\u00e1pido, muchos usuarios asumen que el software es demasiado dif\u00edcil de usar y se van antes de probarlo.<\/p>\n<h3>Regla 4: Escribe un L\u00e9ame Completo<\/h3>\n<p>Suponga que el L\u00e9ame ser\u00e1 la \u00fanica documentaci\u00f3n que leen muchos usuarios. Debe cubrir claramente lo esencial.<\/p>\n<p>Un l\u00e9ame s\u00f3lido debe incluir:<\/p>\n<ul>\n<li>Una breve descripci\u00f3n del proyecto.<\/li>\n<li>Instrucciones de instalaci\u00f3n y dependencias.<\/li>\n<li>Un ejemplo de inicio r\u00e1pido.<\/li>\n<li>Informaci\u00f3n de licencia.<\/li>\n<li>Instrucciones de cita.<\/li>\n<li>Un enlace a la documentaci\u00f3n completa.<\/li>\n<\/ul>\n<p>Plantilla L\u00e9ame:<\/p>\n<pre><code class=\"language-markdown\"># Project Name\n\nShort description: one sentence explaining what the software does.\n\n## Installation\n\n1. Clone this repository.\n2. Run `pip install -e .` or your preferred install command.\n3. Verify the installation:\n\n```python\nimport mypackage\nprint(mypackage.__version__)\n```\n\n## Quickstart\n\n```python\nfrom mypackage import MySimulator\n\nsim = MySimulator(config=\"default.yaml\")\nresults = sim.run()\n```\n\n## Documentation\n\nFull documentation: [Read the Docs link]\n\n## Citation\n\nPlease cite this software using the CITATION.cff file.\n\n## License\n\nMIT License\n<\/code><\/pre>\n<h3>Regla 5: Incluya un comando de ayuda para CLIS<\/h3>\n<p>Si su software tiene una interfaz de l\u00ednea de comandos, incluya un indicador claro <code>--help<\/code>. Debe explicar los comandos, los argumentos requeridos, los par\u00e1metros opcionales y los ejemplos.<\/p>\n<p>Las herramientas de Python como <code>argparse<\/code> hacen que esto sea sencillo.<\/p>\n<h3>Regla 6: Control de versiones de su documentaci\u00f3n<\/h3>\n<p>Guarde la documentaci\u00f3n junto con el c\u00f3digo en el control de versiones. Los usuarios de versiones de software anteriores necesitan acceso a la documentaci\u00f3n que coincida con esas versiones.<\/p>\n<p>Utilice el alojamiento de documentaci\u00f3n con versiones cuando sea posible para que los usuarios puedan cambiar entre versiones.<\/p>\n<h3>Regla 7: Documente su API<\/h3>\n<p>Documente funciones p\u00fablicas, clases, argumentos, valores de retorno y excepciones. Utilice un estilo de docString consistente para que las herramientas automatizadas puedan generar documentaci\u00f3n de API legible.<\/p>\n<p>Ejemplo:<\/p>\n<pre><code class=\"language-python\">def run_simulation(config_path, steps):\n    \"\"\"Run the simulation from a configuration file.\n\n    Args:\n        config_path: Path to the YAML configuration file.\n        steps: Number of time steps to run.\n\n    Returns:\n        Simulation results object with fields, metadata, and diagnostics.\n\n    Raises:\n        ValueError: If the configuration file is invalid.\n    \"\"\"\n    ...\n<\/code><\/pre>\n<h3>Regla 8: Usar herramientas de documentaci\u00f3n automatizada<\/h3>\n<p>No escriba todo manualmente si las herramientas pueden generar parte de \u00e9l. Las herramientas de documentaci\u00f3n automatizadas reducen el trabajo repetitivo y mantienen la documentaci\u00f3n m\u00e1s cerca del c\u00f3digo.<\/p>\n<p>Las herramientas \u00fatiles incluyen:<\/p>\n<ul>\n<li>Sphinx para paquetes de Python con API complejas.<\/li>\n<li>mkdocs para sitios de documentaci\u00f3n simples basados en rebajas.<\/li>\n<li>Lea los documentos para el alojamiento y las compilaciones de documentaci\u00f3n autom\u00e1tica.<\/li>\n<\/ul>\n<h3>Regla 9: Escribir mensajes de error procesables<\/h3>\n<p>Los buenos mensajes de error le dicen a los usuarios qu\u00e9 sali\u00f3 mal, por qu\u00e9 sucedi\u00f3 y c\u00f3mo solucionarlo.<\/p>\n<pre><code class=\"language-python\"># Bad\nraise ValueError(\"Invalid input\")\n\n# Good\nraise ValueError(\n    f\"Input parameter 'temperature' must be between 0 and 3000 K. \"\n    f\"Received {temperature} K. Check your simulation config file.\"\n)\n<\/code><\/pre>\n<p>Esto ahorra tiempo de depuraci\u00f3n y reduce las solicitudes de soporte.<\/p>\n<h3>Regla 10: Dile a la gente c\u00f3mo citar tu software<\/h3>\n<p>Si desea que su software de investigaci\u00f3n reciba cr\u00e9dito, proporcione instrucciones de cita. Incluya un archivo DOI, BibTex y <code>CITATION.cff<\/code>.<\/p>\n<p>Si el software no tiene una publicaci\u00f3n de revista, use Zenodo para acu\u00f1ar un DOI para las versiones. Enviar al software Journal of Open Source tambi\u00e9n puede hacer que el software sea m\u00e1s f\u00e1cil de citar.<\/p>\n<h2>Plantillas de documentaci\u00f3n que puede usar hoy<\/h2>\n<h3>El \u00e1rbol de decisi\u00f3n de documentaci\u00f3n<\/h3>\n<p>Antes de escribir documentaci\u00f3n, haga tres preguntas:<\/p>\n<ol>\n<li>\u00bfPara qui\u00e9n es? \u00bfUsuarios, desarrolladores, mantenedores, revisores o colaboradores?<\/li>\n<li>\u00bfQu\u00e9 quieren? \u00bfEjecutar el software, modificarlo, entender el modelo o citarlo?<\/li>\n<li>\u00bfQu\u00e9 formato se ajusta a la necesidad? \u00bfTutorial, gu\u00eda de instrucciones, referencia, explicaci\u00f3n, comentario en l\u00ednea o p\u00e1gina API?<\/li>\n<\/ol>\n<p>Estas preguntas ayudan a evitar un error com\u00fan: escribir un documento sobrecargado para cada audiencia.<\/p>\n<h3>El formato del archivo de cita<\/h3>\n<p>El archivo <code>CITATION.cff<\/code> es un archivo legible por m\u00e1quina y legible por humanos para la cita de software. Puede incluir:<\/p>\n<ul>\n<li>Nombre y versi\u00f3n del software.<\/li>\n<li>autores y afiliaciones.<\/li>\n<li>doi para el software.<\/li>\n<li>Informaci\u00f3n de Bibtex.<\/li>\n<li>URL del repositorio.<\/li>\n<\/ul>\n<p>Cuando se combina con un Zenodo doi, <code>CITATION.cff<\/code> se convierte en un registro de citas estable para su software.<\/p>\n<h3>Ejemplo Citation.cff plantilla<\/h3>\n<pre><code class=\"language-yaml\">cff-version: 1.2.0\nmessage: \"If you use this software, please cite it as below.\"\ntitle: \"Project Name\"\nversion: \"1.0.0\"\ndoi: \"10.5281\/zenodo.xxxxxxx\"\nauthors:\n  - family-names: \"Surname\"\n    given-names: \"First Name\"\n    affiliation: \"Research Institution\"\nrepository-code: \"https:\/\/github.com\/username\/project-name\"\nlicense: \"MIT\"\n<\/code><\/pre>\n<h2>Herramientas del comercio<\/h2>\n<table class=\"custom-table\">\n<tbody>\n<tr>\n<th>Herramienta<\/th>\n<th>Prop\u00f3sito<\/th>\n<th>mejor para<\/th>\n<\/tr>\n<tr>\n<td>Esfinge<\/td>\n<td>Genera documentaci\u00f3n a partir de docStrings y ReestructuradoTexto o Markdown<\/td>\n<td>Paquetes de Python con API complejas<\/td>\n<\/tr>\n<tr>\n<td>MKDOC<\/td>\n<td>Crea sitios de documentaci\u00f3n basados en Markdown<\/td>\n<td>Proyectos ligeros que necesitan un sitio de documentaci\u00f3n simple<\/td>\n<\/tr>\n<tr>\n<td>Leer los documentos<\/td>\n<td>Documentaci\u00f3n versionada de hosts y compilaciones autom\u00e1ticas<\/td>\n<td>Proyectos que necesitan implementaci\u00f3n autom\u00e1tica de documentaci\u00f3n<\/td>\n<\/tr>\n<tr>\n<td>dox\u00edgeno<\/td>\n<td>Genera documentaci\u00f3n para proyectos C, C++, Python y mixto<\/td>\n<td>Proyectos con C++ o bases de c\u00f3digos cient\u00edficos mixtos<\/td>\n<\/tr>\n<tr>\n<td>zenodo<\/td>\n<td>Lanzamientos de software Mints DOI y Archives<\/td>\n<td>Cita a largo plazo y reproducibilidad<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h2>Errores comunes y c\u00f3mo evitarlos<\/h2>\n<h3>Error 1: Tratar todo como un L\u00e9ame<\/h3>\n<p>Un L\u00e9ame no puede hacer bien todos los trabajos. Si combina tutoriales, referencia, explicaci\u00f3n, detalles de la API y la soluci\u00f3n de problemas en un archivo, los usuarios tienen dificultades para encontrar lo que necesitan.<\/p>\n<p>Separe la documentaci\u00f3n por prop\u00f3sito utilizando los cuadrantes de Di\u00e1taxis.<\/p>\n<h3>Error 2: Escribir explicaci\u00f3n en tutoriales<\/h3>\n<p>Los tutoriales deben ser breves, pr\u00e1cticos y lineales. Si un principiante debe entender el modelo matem\u00e1tico antes de usar el software, ponga esa explicaci\u00f3n en una p\u00e1gina separada y enlace.<\/p>\n<h3>Error 3: no la documentaci\u00f3n que controla la versi\u00f3n<\/h3>\n<p>Si cambia un par\u00e1metro predeterminado en la versi\u00f3n 2.0, los usuarios de la versi\u00f3n 1.5 necesitan la documentaci\u00f3n anterior. Los documentos versionados evitan la confusi\u00f3n y hacen que las versiones anteriores sean m\u00e1s utilizables.<\/p>\n<h3>Error 4: Suponiendo que el futuro lo recordar\u00e1s todo<\/h3>\n<p>Es posible que no recuerde sus decisiones de dise\u00f1o seis meses despu\u00e9s. Las p\u00e1ginas de comentarios y explicaciones sirven como un cuaderno de laboratorio para sus opciones de implementaci\u00f3n.<\/p>\n<h3>Error 5: Olvidar las instrucciones de la cita<\/h3>\n<p>El software sin gu\u00eda de citas a menudo recibe menos cr\u00e9dito. Incluya un archivo DOI, Bibtex y <code>CITATION.cff<\/code> para que los usuarios sepan exactamente c\u00f3mo citar su trabajo.<\/p>\n<h2>Un flujo de trabajo de documentaci\u00f3n pr\u00e1ctica<\/h2>\n<p>Puede implementar la documentaci\u00f3n en etapas. El objetivo no es escribir todo a la vez, sino construir la estructura antes de tiempo y mejorarla a medida que el proyecto madura.<\/p>\n<h3>Fase 1: antes de escribir cualquier c\u00f3digo<\/h3>\n<ol>\n<li>Cree un archivo <code>CITATION.cff<\/code> de borrador.<\/li>\n<li>Elabore un archivo L\u00e9ame esqueleto con el prop\u00f3sito del proyecto, el marcador de posici\u00f3n de la instalaci\u00f3n y la licencia.<\/li>\n<li>Decida si la audiencia principal son los usuarios, desarrolladores, mantenedores o los tres.<\/li>\n<\/ol>\n<h3>Fase 2: Durante el desarrollo<\/h3>\n<ol>\n<li>Escriba los comentarios mientras codifica, especialmente para las opciones algor\u00edtmicas.<\/li>\n<li>Agregue docStrings para cada funci\u00f3n y clase p\u00fablica.<\/li>\n<li>Configure Sphinx o mkdocs antes de tiempo para que la documentaci\u00f3n se construya junto con el c\u00f3digo.<\/li>\n<li>Agregue ejemplos cuando las caracter\u00edsticas se vuelvan estables.<\/li>\n<\/ol>\n<h3>Fase 3: Despu\u00e9s del desarrollo<\/h3>\n<ol>\n<li>Escriba una gu\u00eda de inicio r\u00e1pido.<\/li>\n<li>Complete el L\u00e9ame con las instrucciones de instalaci\u00f3n, uso, licencia y cita.<\/li>\n<li>Escriba al menos una gu\u00eda pr\u00e1ctica para el caso de uso m\u00e1s com\u00fan.<\/li>\n<li>Cree o actualice el DOI a trav\u00e9s de Zenodo, Joss u otra ruta de publicaci\u00f3n adecuada.<\/li>\n<\/ol>\n<h2>Enlaces internos y gu\u00edas relacionadas<\/h2>\n<p>Para temas relacionados en flujos de trabajo de simulaci\u00f3n cient\u00edfica:<\/p>\n<ul>\n<li><a href=\"https:\/\/matforge.org\/documentation-best-practices-scientific-python-packages\/\">Mejores pr\u00e1cticas de documentaci\u00f3n para paquetes cient\u00edficos de Python<\/a> \u2014 Herramientas y documentaci\u00f3n espec\u00edficas de Python estructura.<\/li>\n<li><a href=\"https:\/\/matforge.org\/continuous-integration-research-software-automated-testing-validation\/\">Integraci\u00f3n continua para software de investigaci\u00f3n<\/a> \u2014 CI\/CD para pruebas y validaciones automatizadas.<\/li>\n<li><a href=\"https:\/\/matforge.org\/reading-and-understanding-fipy-documentation\/\">lectura y comprensi\u00f3n de la documentaci\u00f3n de Fipy<\/a> \u2014 Patrones pr\u00e1cticos de documentaci\u00f3n de Fipy.<\/li>\n<li><a href=\"https:\/\/matforge.org\/reproducible-research-workflows-docker-and-conda-for-simulation-projects\/\">Flujos de trabajo de investigaci\u00f3n reproducibles: Docker y conda<\/a> \u2014 Entorno reproducibilidad.<\/li>\n<li><a href=\"https:\/\/matforge.org\/best-practices-for-maintaining-scientific-code\/\">Mejores pr\u00e1cticas para mantener el c\u00f3digo cient\u00edfico<\/a> \u2014 Mantenimiento de proyectos a largo plazo.<\/li>\n<\/ul>\n<h2>Resumen y pr\u00f3ximos pasos<\/h2>\n<p>La documentaci\u00f3n transforma el c\u00f3digo de un artefacto experimental fr\u00e1gil en un activo de investigaci\u00f3n duradero. El marco de di\u00e1taxis da estructura. Las diez reglas simples dan una lista de verificaci\u00f3n pr\u00e1ctica. Las plantillas y las herramientas proporcionan un punto de partida r\u00e1pido.<\/p>\n<p>Comience con un peque\u00f1o paso: cree un archivo <code>CITATION.cff<\/code> y agregue la gu\u00eda de citaci\u00f3n. Esto hace que el software sea m\u00e1s f\u00e1cil de citar y de cr\u00e9dito.<\/p>\n<p>A continuaci\u00f3n, agregue un L\u00e9ame con enlaces de instalaci\u00f3n, inicio r\u00e1pido, licencia y documentaci\u00f3n. Este es el documento m\u00e1s impactante para la usabilidad.<\/p>\n<p>A continuaci\u00f3n, documente la API con docStrings consistentes y configure Sphinx o MKDocs. Esto ayuda a los usuarios y futuros mantenedores a comprender c\u00f3mo funciona el c\u00f3digo.<\/p>\n<p>Finalmente, escriba al menos una gu\u00eda de instrucciones para el caso de uso m\u00e1s com\u00fan. Esa es a menudo la p\u00e1gina que los colaboradores realmente necesitan.<\/p>\n<p>Cada pieza de documentaci\u00f3n hace que su software est\u00e9 un paso m\u00e1s cerca de la investigaci\u00f3n reproducible.<\/p>\n<h2>Referencias y lectura adicional<\/h2>\n<ul>\n<li>Lee, B.D. (2018). Diez reglas simples para documentar software cient\u00edfico. <em>PLOS Biolog\u00eda computacional<\/em>, 14(12): E1006561. <a href=\"https:\/\/doi.org\/10.1371\/journal.pcbi.1006561\">doi: 10.1371\/journal.pcbi.1006561<\/a><\/li>\n<li>Instituto de Sostenibilidad de Software. \u00bfCu\u00e1les son las mejores pr\u00e1cticas para la documentaci\u00f3n de software de investigaci\u00f3n? <a href=\"https:\/\/www.software.ac.uk\/blog\/what-are-best-practices-research-software-documentation\">source<\/a><\/li>\n<li>Procida, D. Di\u00e1taxis: un enfoque sistem\u00e1tico de la creaci\u00f3n de documentaci\u00f3n t\u00e9cnica. <a href=\"https:\/\/diataxis.fr\/\">fuente<\/a><\/li>\n<li>Wilson, G., et al. (2014). Mejores pr\u00e1cticas para la computaci\u00f3n cient\u00edfica. <em>PLOS Biology<\/em>, 12(1): E1001745. <a href=\"https:\/\/doi.org\/10.1371\/journal.pbio.1001745\">doi: 10.1371\/journal.pbio.1001745<\/a><\/li>\n<li>Revista de software de c\u00f3digo abierto. <a href=\"https:\/\/joss.theoj.org\/\">fuente<\/a><\/li>\n<li>Lea los documentos. <a href=\"https:\/\/readthedocs.org\/\">fuente<\/a><\/li>\n<\/ul>\n<h2>\u00bfNecesita ayuda para estructurar la documentaci\u00f3n para su proyecto de simulaci\u00f3n?<\/h2>\n<p>Si su equipo de investigaci\u00f3n necesita ayuda para configurar las canalizaciones de documentaci\u00f3n automatizada, dise\u00f1ar una estructura de documentaci\u00f3n que cumpla con la di\u00e1taxis o integrar la documentaci\u00f3n en los flujos de trabajo de CI\/CD, nuestros expertos en ciencias computacionales pueden ayudarlo.<\/p>\n<p>Cont\u00e1ctenos a trav\u00e9s de nuestro <a href=\"https:\/\/matforge.org\/category\/issue-tracking-tickets-technical-requests\/\">sistema de seguimiento de problemas<\/a> para discutir las necesidades de documentaci\u00f3n de su proyecto.<\/p>\n","protected":false,"raw":"<p>Acabas de terminar una canalizaci\u00f3n de simulaci\u00f3n. Sus resultados est\u00e1n listos para la publicaci\u00f3n. Su c\u00f3digo funciona. Entonces, \u00bfpor qu\u00e9 todav\u00eda necesita documentarlo?<\/p>\n<p>Porque sin documentaci\u00f3n, su software es m\u00e1s dif\u00edcil de citar, m\u00e1s dif\u00edcil de reproducir y m\u00e1s dif\u00edcil de mantener. Es posible que los colaboradores no entiendan c\u00f3mo ejecutarlo. Es posible que los futuros estudiantes no sepan qu\u00e9 archivo de configuraci\u00f3n importa. Incluso puede olvidar las decisiones clave de dise\u00f1o despu\u00e9s de varios meses.<\/p>\n<p>La documentaci\u00f3n no es un complemento agradable para el software de investigaci\u00f3n. Es el puente entre una herramienta de trabajo y un activo de investigaci\u00f3n reproducible. No necesitas ser un escritor t\u00e9cnico para hacerlo bien. Necesitas una estructura.<\/p>\n<h2>Comida clave<\/h2>\n<ul>\n<li>La documentaci\u00f3n forma parte de la investigaci\u00f3n reproducible. El c\u00f3digo sin documentaci\u00f3n se convierte en una caja negra que solo su autor original puede mantener.<\/li>\n<li>Cuatro tipos de documentaci\u00f3n sirven a cuatro necesidades de los usuarios diferentes: tutoriales para el aprendizaje, gu\u00edas pr\u00e1cticas para hacer, referencia para describir y explicaci\u00f3n para la comprensi\u00f3n.<\/li>\n<li>El marco de Di\u00e1taxis es una forma pr\u00e1ctica de organizar la documentaci\u00f3n de software de investigaci\u00f3n.<\/li>\n<li>Las diez reglas simples para documentar software cient\u00edfico proporcionan una lista de verificaci\u00f3n \u00fatil para escribir una mejor documentaci\u00f3n.<\/li>\n<li>Ya existen plantillas y herramientas. Readme Structures, <code>CITATION.cff<\/code> archivos, Sphinx, MKDOC y Read Los documentos hacen que el proceso sea m\u00e1s eficiente.<\/li>\n<\/ul>\n<h2>Por qu\u00e9 importa la documentaci\u00f3n<\/h2>\n<p>El software de investigaci\u00f3n se encuentra entre la ciencia y la ingenier\u00eda. A diferencia del equipo de laboratorio tradicional, el software puede ser compartido, modificado, reutilizado y citado por cualquier persona con el entorno adecuado. Pero ese potencial significa poco si nadie entiende c\u00f3mo funciona el software.<\/p>\n<p>Las apuestas son pr\u00e1cticas:<\/p>\n<ul>\n<li>reproducibilidad. Sin documentaci\u00f3n, otros investigadores no pueden verificar o reutilizar su trabajo de manera confiable.<\/li>\n<li>cita Es menos probable que el software que carece de gu\u00edas de citas e instrucciones de uso reciba el cr\u00e9dito adecuado.<\/li>\n<li>mantenimiento. Cuando un investigador deja un laboratorio, el c\u00f3digo indocumentado a menudo se convierte en deuda t\u00e9cnica para la siguiente persona.<\/li>\n<\/ul>\n<p>Una buena documentaci\u00f3n hace que el software sea m\u00e1s f\u00e1cil de usar, ampliar, revisar y conservar. Tambi\u00e9n reduce el n\u00famero de preguntas repetidas de colaboradores y futuros usuarios.<\/p>\n<p>Esta gu\u00eda le brinda un marco pr\u00e1ctico y plantillas para documentar el software de investigaci\u00f3n de manera efectiva.<\/p>\n<h2>El marco de la Di\u00e1taxis: cuatro tipos de documentaci\u00f3n<\/h2>\n<p>Si su documentaci\u00f3n vive actualmente en un archivo L\u00e9ame largo, puede parecer desorganizado. Los tutoriales, las notas de instalaci\u00f3n, los detalles de la API, la teor\u00eda, los ejemplos y la soluci\u00f3n de problemas pueden mezclarse f\u00e1cilmente.<\/p>\n<p>El marco de Di\u00e1taxis resuelve esto separando la documentaci\u00f3n en cuatro tipos distintos. Cada tipo sirve a una necesidad de usuario diferente.<\/p>\n<h3>1. Tutoriales<\/h3>\n<p>Un tutorial est\u00e1 orientado al aprendizaje. Lleva a un principiante a trav\u00e9s de un camino guiado y lo ayuda a lograr un resultado concreto.<\/p>\n<p>Ejemplo: \u201cConfigurar Fipy para su primera simulaci\u00f3n de campo de fase\u201d.<\/p>\n<p>Un tutorial Respuestas: \u00bfC\u00f3mo aprendo a usar este software?<\/p>\n<h3>2. Gu\u00edas pr\u00e1cticas<\/h3>\n<p>Una gu\u00eda pr\u00e1ctica est\u00e1 orientada a la acci\u00f3n. Ayuda a alguien a completar una tarea espec\u00edfica despu\u00e9s de que ya entiende los conceptos b\u00e1sicos.<\/p>\n<p>Los ejemplos incluyen:<\/p>\n<ul>\n<li>C\u00f3mo ejecutar una simulaci\u00f3n de Monte Carlo con Fipy.<\/li>\n<li>C\u00f3mo solucionar errores de convergencia.<\/li>\n<li>C\u00f3mo exportar los resultados de la simulaci\u00f3n a CSV.<\/li>\n<\/ul>\n<p>Respuestas de una gu\u00eda de instrucciones: \u00bfC\u00f3mo logro una tarea espec\u00edfica?<\/p>\n<h3>3. Referencia<\/h3>\n<p>La documentaci\u00f3n de referencia est\u00e1 orientada a la informaci\u00f3n. Es factual, neutral y completo. Describe lo que proporciona el software sin ense\u00f1ar o persuadir.<\/p>\n<p>Los ejemplos incluyen:<\/p>\n<ul>\n<li>Documentaci\u00f3n de API.<\/li>\n<li>Firmas de funci\u00f3n.<\/li>\n<li>Especificaciones de los par\u00e1metros.<\/li>\n<li>Definiciones de clase.<\/li>\n<\/ul>\n<p>Documentaci\u00f3n de referencia Respuestas: \u00bfQu\u00e9 hace esto?<\/p>\n<h3>4. Explicaci\u00f3n<\/h3>\n<p>La explicaci\u00f3n est\u00e1 orientada a la comprensi\u00f3n. Proporciona antecedentes, contexto, razonamiento y fundamento de dise\u00f1o.<\/p>\n<p>Los ejemplos incluyen:<\/p>\n<ul>\n<li>Por qu\u00e9 el solucionador utiliza un paso de tiempo impl\u00edcito.<\/li>\n<li>El modelo matem\u00e1tico detr\u00e1s de la implementaci\u00f3n.<\/li>\n<li>Por qu\u00e9 se eligi\u00f3 una estrategia de malla sobre otra.<\/li>\n<\/ul>\n<p>Explicaci\u00f3n Respuestas: \u00bfPor qu\u00e9 esto funciona de esta manera?<\/p>\n<h2>Las diez reglas simples para documentar software de investigaci\u00f3n<\/h2>\n<p>Las diez reglas simples para documentar el software cient\u00edfico son una lista de verificaci\u00f3n pr\u00e1ctica para la calidad de la documentaci\u00f3n. Son \u00fatiles porque se enfocan en los h\u00e1bitos que los investigadores pueden aplicar sin construir un departamento de documentaci\u00f3n completo.<\/p>\n<h3>Regla 1: Escribe comentarios mientras codificas<\/h3>\n<p>Los comentarios deben explicar las ideas y el razonamiento detr\u00e1s del algoritmo, no simplemente repetir lo que el c\u00f3digo ya dice.<\/p>\n<pre><code class=\"language-python\"># Good: explains why this approach is used\n# Use implicit time stepping for stiff reaction terms to avoid\n# timestep restrictions that would make the simulation impractical.\nsolver = ImplicitTimeStepping(reaction_terms)\n\n# Bad: repeats the line without explaining intent\nsolver = ImplicitTimeStepping(reaction_terms)  # creates solver\n<\/code><\/pre>\n<h3>Regla 2: Incluya muchos ejemplos<\/h3>\n<p>Los ejemplos muestran a los usuarios c\u00f3mo funciona el software en la pr\u00e1ctica. Proporcione ejemplos ejecutables que demuestren el flujo de trabajo principal.<\/p>\n<p>Si la documentaci\u00f3n est\u00e1 demasiado llena de ejemplos, mu\u00e9valos a un directorio <code>examples\/<\/code> dedicado y vinc\u00falelos desde la documentaci\u00f3n principal.<\/p>\n<h3>Regla 3: Incluya una gu\u00eda de inicio r\u00e1pido<\/h3>\n<p>Una gu\u00eda de inicio r\u00e1pido deber\u00eda permitir que alguien use el software a los pocos minutos de descargarlo. Debe incluir la instalaci\u00f3n, un ejemplo m\u00ednimo y la salida esperada.<\/p>\n<p>Sin un inicio r\u00e1pido, muchos usuarios asumen que el software es demasiado dif\u00edcil de usar y se van antes de probarlo.<\/p>\n<h3>Regla 4: Escribe un L\u00e9ame Completo<\/h3>\n<p>Suponga que el L\u00e9ame ser\u00e1 la \u00fanica documentaci\u00f3n que leen muchos usuarios. Debe cubrir claramente lo esencial.<\/p>\n<p>Un l\u00e9ame s\u00f3lido debe incluir:<\/p>\n<ul>\n<li>Una breve descripci\u00f3n del proyecto.<\/li>\n<li>Instrucciones de instalaci\u00f3n y dependencias.<\/li>\n<li>Un ejemplo de inicio r\u00e1pido.<\/li>\n<li>Informaci\u00f3n de licencia.<\/li>\n<li>Instrucciones de cita.<\/li>\n<li>Un enlace a la documentaci\u00f3n completa.<\/li>\n<\/ul>\n<p>Plantilla L\u00e9ame:<\/p>\n<pre><code class=\"language-markdown\"># Project Name\n\nShort description: one sentence explaining what the software does.\n\n## Installation\n\n1. Clone this repository.\n2. Run `pip install -e .` or your preferred install command.\n3. Verify the installation:\n\n```python\nimport mypackage\nprint(mypackage.__version__)\n```\n\n## Quickstart\n\n```python\nfrom mypackage import MySimulator\n\nsim = MySimulator(config=\"default.yaml\")\nresults = sim.run()\n```\n\n## Documentation\n\nFull documentation: [Read the Docs link]\n\n## Citation\n\nPlease cite this software using the CITATION.cff file.\n\n## License\n\nMIT License\n<\/code><\/pre>\n<h3>Regla 5: Incluya un comando de ayuda para CLIS<\/h3>\n<p>Si su software tiene una interfaz de l\u00ednea de comandos, incluya un indicador claro <code>--help<\/code>. Debe explicar los comandos, los argumentos requeridos, los par\u00e1metros opcionales y los ejemplos.<\/p>\n<p>Las herramientas de Python como <code>argparse<\/code> hacen que esto sea sencillo.<\/p>\n<h3>Regla 6: Control de versiones de su documentaci\u00f3n<\/h3>\n<p>Guarde la documentaci\u00f3n junto con el c\u00f3digo en el control de versiones. Los usuarios de versiones de software anteriores necesitan acceso a la documentaci\u00f3n que coincida con esas versiones.<\/p>\n<p>Utilice el alojamiento de documentaci\u00f3n con versiones cuando sea posible para que los usuarios puedan cambiar entre versiones.<\/p>\n<h3>Regla 7: Documente su API<\/h3>\n<p>Documente funciones p\u00fablicas, clases, argumentos, valores de retorno y excepciones. Utilice un estilo de docString consistente para que las herramientas automatizadas puedan generar documentaci\u00f3n de API legible.<\/p>\n<p>Ejemplo:<\/p>\n<pre><code class=\"language-python\">def run_simulation(config_path, steps):\n    \"\"\"Run the simulation from a configuration file.\n\n    Args:\n        config_path: Path to the YAML configuration file.\n        steps: Number of time steps to run.\n\n    Returns:\n        Simulation results object with fields, metadata, and diagnostics.\n\n    Raises:\n        ValueError: If the configuration file is invalid.\n    \"\"\"\n    ...\n<\/code><\/pre>\n<h3>Regla 8: Usar herramientas de documentaci\u00f3n automatizada<\/h3>\n<p>No escriba todo manualmente si las herramientas pueden generar parte de \u00e9l. Las herramientas de documentaci\u00f3n automatizadas reducen el trabajo repetitivo y mantienen la documentaci\u00f3n m\u00e1s cerca del c\u00f3digo.<\/p>\n<p>Las herramientas \u00fatiles incluyen:<\/p>\n<ul>\n<li>Sphinx para paquetes de Python con API complejas.<\/li>\n<li>mkdocs para sitios de documentaci\u00f3n simples basados en rebajas.<\/li>\n<li>Lea los documentos para el alojamiento y las compilaciones de documentaci\u00f3n autom\u00e1tica.<\/li>\n<\/ul>\n<h3>Regla 9: Escribir mensajes de error procesables<\/h3>\n<p>Los buenos mensajes de error le dicen a los usuarios qu\u00e9 sali\u00f3 mal, por qu\u00e9 sucedi\u00f3 y c\u00f3mo solucionarlo.<\/p>\n<pre><code class=\"language-python\"># Bad\nraise ValueError(\"Invalid input\")\n\n# Good\nraise ValueError(\n    f\"Input parameter 'temperature' must be between 0 and 3000 K. \"\n    f\"Received {temperature} K. Check your simulation config file.\"\n)\n<\/code><\/pre>\n<p>Esto ahorra tiempo de depuraci\u00f3n y reduce las solicitudes de soporte.<\/p>\n<h3>Regla 10: Dile a la gente c\u00f3mo citar tu software<\/h3>\n<p>Si desea que su software de investigaci\u00f3n reciba cr\u00e9dito, proporcione instrucciones de cita. Incluya un archivo DOI, BibTex y <code>CITATION.cff<\/code>.<\/p>\n<p>Si el software no tiene una publicaci\u00f3n de revista, use Zenodo para acu\u00f1ar un DOI para las versiones. Enviar al software Journal of Open Source tambi\u00e9n puede hacer que el software sea m\u00e1s f\u00e1cil de citar.<\/p>\n<h2>Plantillas de documentaci\u00f3n que puede usar hoy<\/h2>\n<h3>El \u00e1rbol de decisi\u00f3n de documentaci\u00f3n<\/h3>\n<p>Antes de escribir documentaci\u00f3n, haga tres preguntas:<\/p>\n<ol>\n<li>\u00bfPara qui\u00e9n es? \u00bfUsuarios, desarrolladores, mantenedores, revisores o colaboradores?<\/li>\n<li>\u00bfQu\u00e9 quieren? \u00bfEjecutar el software, modificarlo, entender el modelo o citarlo?<\/li>\n<li>\u00bfQu\u00e9 formato se ajusta a la necesidad? \u00bfTutorial, gu\u00eda de instrucciones, referencia, explicaci\u00f3n, comentario en l\u00ednea o p\u00e1gina API?<\/li>\n<\/ol>\n<p>Estas preguntas ayudan a evitar un error com\u00fan: escribir un documento sobrecargado para cada audiencia.<\/p>\n<h3>El formato del archivo de cita<\/h3>\n<p>El archivo <code>CITATION.cff<\/code> es un archivo legible por m\u00e1quina y legible por humanos para la cita de software. Puede incluir:<\/p>\n<ul>\n<li>Nombre y versi\u00f3n del software.<\/li>\n<li>autores y afiliaciones.<\/li>\n<li>doi para el software.<\/li>\n<li>Informaci\u00f3n de Bibtex.<\/li>\n<li>URL del repositorio.<\/li>\n<\/ul>\n<p>Cuando se combina con un Zenodo doi, <code>CITATION.cff<\/code> se convierte en un registro de citas estable para su software.<\/p>\n<h3>Ejemplo Citation.cff plantilla<\/h3>\n<pre><code class=\"language-yaml\">cff-version: 1.2.0\nmessage: \"If you use this software, please cite it as below.\"\ntitle: \"Project Name\"\nversion: \"1.0.0\"\ndoi: \"10.5281\/zenodo.xxxxxxx\"\nauthors:\n  - family-names: \"Surname\"\n    given-names: \"First Name\"\n    affiliation: \"Research Institution\"\nrepository-code: \"https:\/\/github.com\/username\/project-name\"\nlicense: \"MIT\"\n<\/code><\/pre>\n<h2>Herramientas del comercio<\/h2>\n<table class=\"custom-table\">\n<tbody><tr>\n<th>Herramienta<\/th>\n<th>Prop\u00f3sito<\/th>\n<th>mejor para<\/th>\n<\/tr>\n<tr>\n<td>Esfinge<\/td>\n<td>Genera documentaci\u00f3n a partir de docStrings y ReestructuradoTexto o Markdown<\/td>\n<td>Paquetes de Python con API complejas<\/td>\n<\/tr>\n<tr>\n<td>MKDOC<\/td>\n<td>Crea sitios de documentaci\u00f3n basados en Markdown<\/td>\n<td>Proyectos ligeros que necesitan un sitio de documentaci\u00f3n simple<\/td>\n<\/tr>\n<tr>\n<td>Leer los documentos<\/td>\n<td>Documentaci\u00f3n versionada de hosts y compilaciones autom\u00e1ticas<\/td>\n<td>Proyectos que necesitan implementaci\u00f3n autom\u00e1tica de documentaci\u00f3n<\/td>\n<\/tr>\n<tr>\n<td>dox\u00edgeno<\/td>\n<td>Genera documentaci\u00f3n para proyectos C, C++, Python y mixto<\/td>\n<td>Proyectos con C++ o bases de c\u00f3digos cient\u00edficos mixtos<\/td>\n<\/tr>\n<tr>\n<td>zenodo<\/td>\n<td>Lanzamientos de software Mints DOI y Archives<\/td>\n<td>Cita a largo plazo y reproducibilidad<\/td>\n<\/tr>\n<\/tbody><\/table>\n<h2>Errores comunes y c\u00f3mo evitarlos<\/h2>\n<h3>Error 1: Tratar todo como un L\u00e9ame<\/h3>\n<p>Un L\u00e9ame no puede hacer bien todos los trabajos. Si combina tutoriales, referencia, explicaci\u00f3n, detalles de la API y la soluci\u00f3n de problemas en un archivo, los usuarios tienen dificultades para encontrar lo que necesitan.<\/p>\n<p>Separe la documentaci\u00f3n por prop\u00f3sito utilizando los cuadrantes de Di\u00e1taxis.<\/p>\n<h3>Error 2: Escribir explicaci\u00f3n en tutoriales<\/h3>\n<p>Los tutoriales deben ser breves, pr\u00e1cticos y lineales. Si un principiante debe entender el modelo matem\u00e1tico antes de usar el software, ponga esa explicaci\u00f3n en una p\u00e1gina separada y enlace.<\/p>\n<h3>Error 3: no la documentaci\u00f3n que controla la versi\u00f3n<\/h3>\n<p>Si cambia un par\u00e1metro predeterminado en la versi\u00f3n 2.0, los usuarios de la versi\u00f3n 1.5 necesitan la documentaci\u00f3n anterior. Los documentos versionados evitan la confusi\u00f3n y hacen que las versiones anteriores sean m\u00e1s utilizables.<\/p>\n<h3>Error 4: Suponiendo que el futuro lo recordar\u00e1s todo<\/h3>\n<p>Es posible que no recuerde sus decisiones de dise\u00f1o seis meses despu\u00e9s. Las p\u00e1ginas de comentarios y explicaciones sirven como un cuaderno de laboratorio para sus opciones de implementaci\u00f3n.<\/p>\n<h3>Error 5: Olvidar las instrucciones de la cita<\/h3>\n<p>El software sin gu\u00eda de citas a menudo recibe menos cr\u00e9dito. Incluya un archivo DOI, Bibtex y <code>CITATION.cff<\/code> para que los usuarios sepan exactamente c\u00f3mo citar su trabajo.<\/p>\n<h2>Un flujo de trabajo de documentaci\u00f3n pr\u00e1ctica<\/h2>\n<p>Puede implementar la documentaci\u00f3n en etapas. El objetivo no es escribir todo a la vez, sino construir la estructura antes de tiempo y mejorarla a medida que el proyecto madura.<\/p>\n<h3>Fase 1: antes de escribir cualquier c\u00f3digo<\/h3>\n<ol>\n<li>Cree un archivo <code>CITATION.cff<\/code> de borrador.<\/li>\n<li>Elabore un archivo L\u00e9ame esqueleto con el prop\u00f3sito del proyecto, el marcador de posici\u00f3n de la instalaci\u00f3n y la licencia.<\/li>\n<li>Decida si la audiencia principal son los usuarios, desarrolladores, mantenedores o los tres.<\/li>\n<\/ol>\n<h3>Fase 2: Durante el desarrollo<\/h3>\n<ol>\n<li>Escriba los comentarios mientras codifica, especialmente para las opciones algor\u00edtmicas.<\/li>\n<li>Agregue docStrings para cada funci\u00f3n y clase p\u00fablica.<\/li>\n<li>Configure Sphinx o mkdocs antes de tiempo para que la documentaci\u00f3n se construya junto con el c\u00f3digo.<\/li>\n<li>Agregue ejemplos cuando las caracter\u00edsticas se vuelvan estables.<\/li>\n<\/ol>\n<h3>Fase 3: Despu\u00e9s del desarrollo<\/h3>\n<ol>\n<li>Escriba una gu\u00eda de inicio r\u00e1pido.<\/li>\n<li>Complete el L\u00e9ame con las instrucciones de instalaci\u00f3n, uso, licencia y cita.<\/li>\n<li>Escriba al menos una gu\u00eda pr\u00e1ctica para el caso de uso m\u00e1s com\u00fan.<\/li>\n<li>Cree o actualice el DOI a trav\u00e9s de Zenodo, Joss u otra ruta de publicaci\u00f3n adecuada.<\/li>\n<\/ol>\n<h2>Enlaces internos y gu\u00edas relacionadas<\/h2>\n<p>Para temas relacionados en flujos de trabajo de simulaci\u00f3n cient\u00edfica:<\/p>\n<ul>\n<li><a href=\"https:\/\/matforge.org\/documentation-best-practices-scientific-python-packages\/\">Mejores pr\u00e1cticas de documentaci\u00f3n para paquetes cient\u00edficos de Python<\/a> \u2014 Herramientas y documentaci\u00f3n espec\u00edficas de Python estructura.<\/li>\n<li><a href=\"https:\/\/matforge.org\/continuous-integration-research-software-automated-testing-validation\/\">Integraci\u00f3n continua para software de investigaci\u00f3n<\/a> \u2014 CI\/CD para pruebas y validaciones automatizadas.<\/li>\n<li><a href=\"https:\/\/matforge.org\/reading-and-understanding-fipy-documentation\/\">lectura y comprensi\u00f3n de la documentaci\u00f3n de Fipy<\/a> \u2014 Patrones pr\u00e1cticos de documentaci\u00f3n de Fipy.<\/li>\n<li><a href=\"https:\/\/matforge.org\/reproducible-research-workflows-docker-and-conda-for-simulation-projects\/\">Flujos de trabajo de investigaci\u00f3n reproducibles: Docker y conda<\/a> \u2014 Entorno reproducibilidad.<\/li>\n<li><a href=\"https:\/\/matforge.org\/best-practices-for-maintaining-scientific-code\/\">Mejores pr\u00e1cticas para mantener el c\u00f3digo cient\u00edfico<\/a> \u2014 Mantenimiento de proyectos a largo plazo.<\/li>\n<\/ul>\n<h2>Resumen y pr\u00f3ximos pasos<\/h2>\n<p>La documentaci\u00f3n transforma el c\u00f3digo de un artefacto experimental fr\u00e1gil en un activo de investigaci\u00f3n duradero. El marco de di\u00e1taxis da estructura. Las diez reglas simples dan una lista de verificaci\u00f3n pr\u00e1ctica. Las plantillas y las herramientas proporcionan un punto de partida r\u00e1pido.<\/p>\n<p>Comience con un peque\u00f1o paso: cree un archivo <code>CITATION.cff<\/code> y agregue la gu\u00eda de citaci\u00f3n. Esto hace que el software sea m\u00e1s f\u00e1cil de citar y de cr\u00e9dito.<\/p>\n<p>A continuaci\u00f3n, agregue un L\u00e9ame con enlaces de instalaci\u00f3n, inicio r\u00e1pido, licencia y documentaci\u00f3n. Este es el documento m\u00e1s impactante para la usabilidad.<\/p>\n<p>A continuaci\u00f3n, documente la API con docStrings consistentes y configure Sphinx o MKDocs. Esto ayuda a los usuarios y futuros mantenedores a comprender c\u00f3mo funciona el c\u00f3digo.<\/p>\n<p>Finalmente, escriba al menos una gu\u00eda de instrucciones para el caso de uso m\u00e1s com\u00fan. Esa es a menudo la p\u00e1gina que los colaboradores realmente necesitan.<\/p>\n<p>Cada pieza de documentaci\u00f3n hace que su software est\u00e9 un paso m\u00e1s cerca de la investigaci\u00f3n reproducible.<\/p>\n<h2>Referencias y lectura adicional<\/h2>\n<ul>\n<li>Lee, B.D. (2018). Diez reglas simples para documentar software cient\u00edfico. <em>PLOS Biolog\u00eda computacional<\/em>, 14(12): E1006561. <a href=\"https:\/\/doi.org\/10.1371\/journal.pcbi.1006561\">doi: 10.1371\/journal.pcbi.1006561<\/a><\/li>\n<li>Instituto de Sostenibilidad de Software. \u00bfCu\u00e1les son las mejores pr\u00e1cticas para la documentaci\u00f3n de software de investigaci\u00f3n? <a href=\"https:\/\/www.software.ac.uk\/blog\/what-are-best-practices-research-software-documentation\">source<\/a><\/li>\n<li>Procida, D. Di\u00e1taxis: un enfoque sistem\u00e1tico de la creaci\u00f3n de documentaci\u00f3n t\u00e9cnica. <a href=\"https:\/\/diataxis.fr\/\">fuente<\/a><\/li>\n<li>Wilson, G., et al. (2014). Mejores pr\u00e1cticas para la computaci\u00f3n cient\u00edfica. <em>PLOS Biology<\/em>, 12(1): E1001745. <a href=\"https:\/\/doi.org\/10.1371\/journal.pbio.1001745\">doi: 10.1371\/journal.pbio.1001745<\/a><\/li>\n<li>Revista de software de c\u00f3digo abierto. <a href=\"https:\/\/joss.theoj.org\/\">fuente<\/a><\/li>\n<li>Lea los documentos. <a href=\"https:\/\/readthedocs.org\/\">fuente<\/a><\/li>\n<\/ul>\n<h2>\u00bfNecesita ayuda para estructurar la documentaci\u00f3n para su proyecto de simulaci\u00f3n?<\/h2>\n<p>Si su equipo de investigaci\u00f3n necesita ayuda para configurar las canalizaciones de documentaci\u00f3n automatizada, dise\u00f1ar una estructura de documentaci\u00f3n que cumpla con la di\u00e1taxis o integrar la documentaci\u00f3n en los flujos de trabajo de CI\/CD, nuestros expertos en ciencias computacionales pueden ayudarlo.<\/p>\n<p>Cont\u00e1ctenos a trav\u00e9s de nuestro <a href=\"https:\/\/matforge.org\/category\/issue-tracking-tickets-technical-requests\/\">sistema de seguimiento de problemas<\/a> para discutir las necesidades de documentaci\u00f3n de su proyecto.<\/p>\n"},"excerpt":{"rendered":"<p><span class=\"span-reading-time rt-reading-time\" style=\"display: block;\"><span class=\"rt-label rt-prefix\">Reading Time: <\/span> <span class=\"rt-time\"> 9<\/span> <span class=\"rt-label rt-postfix\">minutes<\/span><\/span>Aprenda c\u00f3mo documentar software de investigaci\u00f3n con plantillas pr\u00e1cticas, el marco de Di\u00e1taxis y estrategias comprobadas del Software de Sostenibilidad del Software y de las directrices PLOS.<\/p>\n","protected":false,"raw":"Aprenda c\u00f3mo documentar software de investigaci\u00f3n con plantillas pr\u00e1cticas, el marco de Di\u00e1taxis y estrategias comprobadas del Software de Sostenibilidad del Software y de las directrices PLOS."},"author":4,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_locale":"es_ES","_original_post":"https:\/\/matforge.org\/?p=342","iawp_total_views":0,"footnotes":""},"categories":[3],"tags":[],"class_list":["post-555","post","type-post","status-publish","format-standard","hentry","category-issue-tracking-tickets-technical-requests","es-ES"],"yoast_head":"<!-- This site is optimized with the Yoast SEO plugin v28.1 - https:\/\/yoast.com\/product\/yoast-seo-wordpress\/ -->\n<title>Gu\u00eda de documentaci\u00f3n de software de investigaci\u00f3n<\/title>\n<meta name=\"description\" content=\"Aprenda c\u00f3mo documentar software de investigaci\u00f3n con di\u00e1taxis, plantillas L\u00e9ame, Citation.cff, Sphinx, MKdocs, lea los documentos y las reglas pr\u00e1cticas.\" \/>\n<meta name=\"robots\" content=\"index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1\" \/>\n<link rel=\"canonical\" href=\"https:\/\/matforge.org\/es\/research-software-documentation-practical-guide-scientists\/\" \/>\n<meta property=\"og:locale\" content=\"es_ES\" \/>\n<meta property=\"og:type\" content=\"article\" \/>\n<meta property=\"og:title\" content=\"Gu\u00eda de documentaci\u00f3n de software de investigaci\u00f3n\" \/>\n<meta property=\"og:description\" content=\"Aprenda c\u00f3mo documentar software de investigaci\u00f3n con di\u00e1taxis, plantillas L\u00e9ame, Citation.cff, Sphinx, MKdocs, lea los documentos y las reglas pr\u00e1cticas.\" \/>\n<meta property=\"og:url\" content=\"https:\/\/matforge.org\/es\/research-software-documentation-practical-guide-scientists\/\" \/>\n<meta property=\"og:site_name\" content=\"matforge.org\" \/>\n<meta property=\"article:published_time\" content=\"2026-07-22T08:17:36+00:00\" \/>\n<meta name=\"author\" content=\"Priya Nair\" \/>\n<meta name=\"twitter:card\" content=\"summary_large_image\" \/>\n<meta name=\"twitter:label1\" content=\"Escrito por\" \/>\n\t<meta name=\"twitter:data1\" content=\"Priya Nair\" \/>\n\t<meta name=\"twitter:label2\" content=\"Tiempo de lectura\" \/>\n\t<meta name=\"twitter:data2\" content=\"14 minutos\" \/>\n<script type=\"application\/ld+json\" class=\"yoast-schema-graph\">{\"@context\":\"https:\\\/\\\/schema.org\",\"@graph\":[{\"@type\":\"Article\",\"@id\":\"https:\\\/\\\/matforge.org\\\/es\\\/research-software-documentation-practical-guide-scientists\\\/#article\",\"isPartOf\":{\"@id\":\"https:\\\/\\\/matforge.org\\\/es\\\/research-software-documentation-practical-guide-scientists\\\/\"},\"author\":{\"name\":\"Priya Nair\",\"@id\":\"https:\\\/\\\/matforge.org\\\/#\\\/schema\\\/person\\\/2effd7bc155a5e6357f31dac970c5795\"},\"headline\":\"Documentaci\u00f3n de software de investigaci\u00f3n: una gu\u00eda pr\u00e1ctica para cient\u00edficos\",\"datePublished\":\"2026-07-22T08:17:36+00:00\",\"mainEntityOfPage\":{\"@id\":\"https:\\\/\\\/matforge.org\\\/es\\\/research-software-documentation-practical-guide-scientists\\\/\"},\"wordCount\":2541,\"commentCount\":0,\"articleSection\":[\"Seguimiento de problemas, tickets &amp; Solicitudes T\u00e9cnicas\"],\"inLanguage\":\"es\",\"potentialAction\":[{\"@type\":\"CommentAction\",\"name\":\"Comment\",\"target\":[\"https:\\\/\\\/matforge.org\\\/es\\\/research-software-documentation-practical-guide-scientists\\\/#respond\"]}]},{\"@type\":\"WebPage\",\"@id\":\"https:\\\/\\\/matforge.org\\\/es\\\/research-software-documentation-practical-guide-scientists\\\/\",\"url\":\"https:\\\/\\\/matforge.org\\\/es\\\/research-software-documentation-practical-guide-scientists\\\/\",\"name\":\"Gu\u00eda de documentaci\u00f3n de software de investigaci\u00f3n\",\"isPartOf\":{\"@id\":\"https:\\\/\\\/matforge.org\\\/#website\"},\"datePublished\":\"2026-07-22T08:17:36+00:00\",\"author\":{\"@id\":\"https:\\\/\\\/matforge.org\\\/#\\\/schema\\\/person\\\/2effd7bc155a5e6357f31dac970c5795\"},\"description\":\"Aprenda c\u00f3mo documentar software de investigaci\u00f3n con di\u00e1taxis, plantillas L\u00e9ame, Citation.cff, Sphinx, MKdocs, lea los documentos y las reglas pr\u00e1cticas.\",\"breadcrumb\":{\"@id\":\"https:\\\/\\\/matforge.org\\\/es\\\/research-software-documentation-practical-guide-scientists\\\/#breadcrumb\"},\"inLanguage\":\"es\",\"potentialAction\":[{\"@type\":\"ReadAction\",\"target\":[\"https:\\\/\\\/matforge.org\\\/es\\\/research-software-documentation-practical-guide-scientists\\\/\"]}]},{\"@type\":\"BreadcrumbList\",\"@id\":\"https:\\\/\\\/matforge.org\\\/es\\\/research-software-documentation-practical-guide-scientists\\\/#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Home\",\"item\":\"https:\\\/\\\/matforge.org\\\/es\\\/\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Documentaci\u00f3n de software de investigaci\u00f3n: una gu\u00eda pr\u00e1ctica para cient\u00edficos\"}]},{\"@type\":\"WebSite\",\"@id\":\"https:\\\/\\\/matforge.org\\\/#website\",\"url\":\"https:\\\/\\\/matforge.org\\\/\",\"name\":\"matforge.org\",\"description\":\"\",\"potentialAction\":[{\"@type\":\"SearchAction\",\"target\":{\"@type\":\"EntryPoint\",\"urlTemplate\":\"https:\\\/\\\/matforge.org\\\/?s={search_term_string}\"},\"query-input\":{\"@type\":\"PropertyValueSpecification\",\"valueRequired\":true,\"valueName\":\"search_term_string\"}}],\"inLanguage\":\"es\"},{\"@type\":\"Person\",\"@id\":\"https:\\\/\\\/matforge.org\\\/#\\\/schema\\\/person\\\/2effd7bc155a5e6357f31dac970c5795\",\"name\":\"Priya Nair\",\"image\":{\"@type\":\"ImageObject\",\"inLanguage\":\"es\",\"@id\":\"https:\\\/\\\/secure.gravatar.com\\\/avatar\\\/f11e168d4cd2f1eff83cbb851d6cff42d81d88bb59d8831ee77468aa4a5eea88?s=96&d=mm&r=g\",\"url\":\"https:\\\/\\\/secure.gravatar.com\\\/avatar\\\/f11e168d4cd2f1eff83cbb851d6cff42d81d88bb59d8831ee77468aa4a5eea88?s=96&d=mm&r=g\",\"contentUrl\":\"https:\\\/\\\/secure.gravatar.com\\\/avatar\\\/f11e168d4cd2f1eff83cbb851d6cff42d81d88bb59d8831ee77468aa4a5eea88?s=96&d=mm&r=g\",\"caption\":\"Priya Nair\"},\"sameAs\":[\"http:\\\/\\\/matforge.org\"],\"url\":\"https:\\\/\\\/matforge.org\\\/author\\\/priya-nair\\\/\"}]}<\/script>\n<!-- \/ Yoast SEO plugin. -->","yoast_head_json":{"title":"Gu\u00eda de documentaci\u00f3n de software de investigaci\u00f3n","description":"Aprenda c\u00f3mo documentar software de investigaci\u00f3n con di\u00e1taxis, plantillas L\u00e9ame, Citation.cff, Sphinx, MKdocs, lea los documentos y las reglas pr\u00e1cticas.","robots":{"index":"index","follow":"follow","max-snippet":"max-snippet:-1","max-image-preview":"max-image-preview:large","max-video-preview":"max-video-preview:-1"},"canonical":"https:\/\/matforge.org\/es\/research-software-documentation-practical-guide-scientists\/","og_locale":"es_ES","og_type":"article","og_title":"Gu\u00eda de documentaci\u00f3n de software de investigaci\u00f3n","og_description":"Aprenda c\u00f3mo documentar software de investigaci\u00f3n con di\u00e1taxis, plantillas L\u00e9ame, Citation.cff, Sphinx, MKdocs, lea los documentos y las reglas pr\u00e1cticas.","og_url":"https:\/\/matforge.org\/es\/research-software-documentation-practical-guide-scientists\/","og_site_name":"matforge.org","article_published_time":"2026-07-22T08:17:36+00:00","author":"Priya Nair","twitter_card":"summary_large_image","twitter_misc":{"Escrito por":"Priya Nair","Tiempo de lectura":"14 minutos"},"schema":{"@context":"https:\/\/schema.org","@graph":[{"@type":"Article","@id":"https:\/\/matforge.org\/es\/research-software-documentation-practical-guide-scientists\/#article","isPartOf":{"@id":"https:\/\/matforge.org\/es\/research-software-documentation-practical-guide-scientists\/"},"author":{"name":"Priya Nair","@id":"https:\/\/matforge.org\/#\/schema\/person\/2effd7bc155a5e6357f31dac970c5795"},"headline":"Documentaci\u00f3n de software de investigaci\u00f3n: una gu\u00eda pr\u00e1ctica para cient\u00edficos","datePublished":"2026-07-22T08:17:36+00:00","mainEntityOfPage":{"@id":"https:\/\/matforge.org\/es\/research-software-documentation-practical-guide-scientists\/"},"wordCount":2541,"commentCount":0,"articleSection":["Seguimiento de problemas, tickets &amp; Solicitudes T\u00e9cnicas"],"inLanguage":"es","potentialAction":[{"@type":"CommentAction","name":"Comment","target":["https:\/\/matforge.org\/es\/research-software-documentation-practical-guide-scientists\/#respond"]}]},{"@type":"WebPage","@id":"https:\/\/matforge.org\/es\/research-software-documentation-practical-guide-scientists\/","url":"https:\/\/matforge.org\/es\/research-software-documentation-practical-guide-scientists\/","name":"Gu\u00eda de documentaci\u00f3n de software de investigaci\u00f3n","isPartOf":{"@id":"https:\/\/matforge.org\/#website"},"datePublished":"2026-07-22T08:17:36+00:00","author":{"@id":"https:\/\/matforge.org\/#\/schema\/person\/2effd7bc155a5e6357f31dac970c5795"},"description":"Aprenda c\u00f3mo documentar software de investigaci\u00f3n con di\u00e1taxis, plantillas L\u00e9ame, Citation.cff, Sphinx, MKdocs, lea los documentos y las reglas pr\u00e1cticas.","breadcrumb":{"@id":"https:\/\/matforge.org\/es\/research-software-documentation-practical-guide-scientists\/#breadcrumb"},"inLanguage":"es","potentialAction":[{"@type":"ReadAction","target":["https:\/\/matforge.org\/es\/research-software-documentation-practical-guide-scientists\/"]}]},{"@type":"BreadcrumbList","@id":"https:\/\/matforge.org\/es\/research-software-documentation-practical-guide-scientists\/#breadcrumb","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https:\/\/matforge.org\/es\/"},{"@type":"ListItem","position":2,"name":"Documentaci\u00f3n de software de investigaci\u00f3n: una gu\u00eda pr\u00e1ctica para cient\u00edficos"}]},{"@type":"WebSite","@id":"https:\/\/matforge.org\/#website","url":"https:\/\/matforge.org\/","name":"matforge.org","description":"","potentialAction":[{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https:\/\/matforge.org\/?s={search_term_string}"},"query-input":{"@type":"PropertyValueSpecification","valueRequired":true,"valueName":"search_term_string"}}],"inLanguage":"es"},{"@type":"Person","@id":"https:\/\/matforge.org\/#\/schema\/person\/2effd7bc155a5e6357f31dac970c5795","name":"Priya Nair","image":{"@type":"ImageObject","inLanguage":"es","@id":"https:\/\/secure.gravatar.com\/avatar\/f11e168d4cd2f1eff83cbb851d6cff42d81d88bb59d8831ee77468aa4a5eea88?s=96&d=mm&r=g","url":"https:\/\/secure.gravatar.com\/avatar\/f11e168d4cd2f1eff83cbb851d6cff42d81d88bb59d8831ee77468aa4a5eea88?s=96&d=mm&r=g","contentUrl":"https:\/\/secure.gravatar.com\/avatar\/f11e168d4cd2f1eff83cbb851d6cff42d81d88bb59d8831ee77468aa4a5eea88?s=96&d=mm&r=g","caption":"Priya Nair"},"sameAs":["http:\/\/matforge.org"],"url":"https:\/\/matforge.org\/author\/priya-nair\/"}]}},"_links":{"self":[{"href":"https:\/\/matforge.org\/wp-json\/wp\/v2\/posts\/555","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/matforge.org\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/matforge.org\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/matforge.org\/wp-json\/wp\/v2\/users\/4"}],"replies":[{"embeddable":true,"href":"https:\/\/matforge.org\/wp-json\/wp\/v2\/comments?post=555"}],"version-history":[{"count":1,"href":"https:\/\/matforge.org\/wp-json\/wp\/v2\/posts\/555\/revisions"}],"predecessor-version":[{"id":734,"href":"https:\/\/matforge.org\/wp-json\/wp\/v2\/posts\/555\/revisions\/734"}],"wp:attachment":[{"href":"https:\/\/matforge.org\/wp-json\/wp\/v2\/media?parent=555"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/matforge.org\/wp-json\/wp\/v2\/categories?post=555"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/matforge.org\/wp-json\/wp\/v2\/tags?post=555"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}