Documentación de software de investigación: una guía práctica para científicos

Acabas de terminar una canalización de simulación. Sus resultados están listos para la publicación. Su código funciona. Entonces, ¿por qué todavía necesita documentarlo?

Porque sin documentación, su software es más difícil de citar, más difícil de reproducir y más difícil de mantener. Es posible que los colaboradores no entiendan cómo ejecutarlo. Es posible que los futuros estudiantes no sepan qué archivo de configuración importa. Incluso puede olvidar las decisiones clave de diseño después de varios meses.

La documentación no es un complemento agradable para el software de investigación. Es el puente entre una herramienta de trabajo y un activo de investigación reproducible. No necesitas ser un escritor técnico para hacerlo bien. Necesitas una estructura.

Comida clave

• La documentación forma parte de la investigación reproducible. El código sin documentación se convierte en una caja negra que solo su autor original puede mantener.
• Cuatro tipos de documentación sirven a cuatro necesidades de los usuarios diferentes: tutoriales para el aprendizaje, guías prácticas para hacer, referencia para describir y explicación para la comprensión.
• El marco de Diátaxis es una forma práctica de organizar la documentación de software de investigación.
• Las diez reglas simples para documentar software científico proporcionan una lista de verificación útil para escribir una mejor documentación.
• Ya existen plantillas y herramientas. Readme Structures, CITATION.cff archivos, Sphinx, MKDOC y Read Los documentos hacen que el proceso sea más eficiente.

Por qué importa la documentación

El software de investigación se encuentra entre la ciencia y la ingeniería. 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ómo funciona el software.

Las apuestas son prácticas:

• reproducibilidad. Sin documentación, otros investigadores no pueden verificar o reutilizar su trabajo de manera confiable.
• cita Es menos probable que el software que carece de guías de citas e instrucciones de uso reciba el crédito adecuado.
• mantenimiento. Cuando un investigador deja un laboratorio, el código indocumentado a menudo se convierte en deuda técnica para la siguiente persona.

Una buena documentación hace que el software sea más fácil de usar, ampliar, revisar y conservar. También reduce el número de preguntas repetidas de colaboradores y futuros usuarios.

Esta guía le brinda un marco práctico y plantillas para documentar el software de investigación de manera efectiva.

El marco de la Diátaxis: cuatro tipos de documentación

Si su documentación vive actualmente en un archivo Léame largo, puede parecer desorganizado. Los tutoriales, las notas de instalación, los detalles de la API, la teoría, los ejemplos y la solución de problemas pueden mezclarse fácilmente.

El marco de Diátaxis resuelve esto separando la documentación en cuatro tipos distintos. Cada tipo sirve a una necesidad de usuario diferente.

1. Tutoriales

Un tutorial está orientado al aprendizaje. Lleva a un principiante a través de un camino guiado y lo ayuda a lograr un resultado concreto.

Ejemplo: “Configurar Fipy para su primera simulación de campo de fase”.

Un tutorial Respuestas: ¿Cómo aprendo a usar este software?

2. Guías prácticas

Una guía práctica está orientada a la acción. Ayuda a alguien a completar una tarea específica después de que ya entiende los conceptos básicos.

Los ejemplos incluyen:

• Cómo ejecutar una simulación de Monte Carlo con Fipy.
• Cómo solucionar errores de convergencia.
• Cómo exportar los resultados de la simulación a CSV.

Respuestas de una guía de instrucciones: ¿Cómo logro una tarea específica?

3. Referencia

La documentación de referencia está orientada a la información. Es factual, neutral y completo. Describe lo que proporciona el software sin enseñar o persuadir.

Los ejemplos incluyen:

• Documentación de API.
• Firmas de función.
• Especificaciones de los parámetros.
• Definiciones de clase.

Documentación de referencia Respuestas: ¿Qué hace esto?

4. Explicación

La explicación está orientada a la comprensión. Proporciona antecedentes, contexto, razonamiento y fundamento de diseño.

Los ejemplos incluyen:

• Por qué el solucionador utiliza un paso de tiempo implícito.
• El modelo matemático detrás de la implementación.
• Por qué se eligió una estrategia de malla sobre otra.

Explicación Respuestas: ¿Por qué esto funciona de esta manera?

Las diez reglas simples para documentar software de investigación

Las diez reglas simples para documentar el software científico son una lista de verificación práctica para la calidad de la documentación. Son útiles porque se enfocan en los hábitos que los investigadores pueden aplicar sin construir un departamento de documentación completo.

Regla 1: Escribe comentarios mientras codificas

Los comentarios deben explicar las ideas y el razonamiento detrás del algoritmo, no simplemente repetir lo que el código ya dice.

# Good: explains why this approach is used
# Use implicit time stepping for stiff reaction terms to avoid
# timestep restrictions that would make the simulation impractical.
solver = ImplicitTimeStepping(reaction_terms)

# Bad: repeats the line without explaining intent
solver = ImplicitTimeStepping(reaction_terms)  # creates solver

Regla 2: Incluya muchos ejemplos

Los ejemplos muestran a los usuarios cómo funciona el software en la práctica. Proporcione ejemplos ejecutables que demuestren el flujo de trabajo principal.

Si la documentación está demasiado llena de ejemplos, muévalos a un directorio examples/ dedicado y vincúlelos desde la documentación principal.

Regla 3: Incluya una guía de inicio rápido

Una guía de inicio rápido debería permitir que alguien use el software a los pocos minutos de descargarlo. Debe incluir la instalación, un ejemplo mínimo y la salida esperada.

Sin un inicio rápido, muchos usuarios asumen que el software es demasiado difícil de usar y se van antes de probarlo.

Regla 4: Escribe un Léame Completo

Suponga que el Léame será la única documentación que leen muchos usuarios. Debe cubrir claramente lo esencial.

Un léame sólido debe incluir:

• Una breve descripción del proyecto.
• Instrucciones de instalación y dependencias.
• Un ejemplo de inicio rápido.
• Información de licencia.
• Instrucciones de cita.
• Un enlace a la documentación completa.

Plantilla Léame:

# Project Name

Short description: one sentence explaining what the software does.

## Installation

1. Clone this repository.
2. Run `pip install -e .` or your preferred install command.
3. Verify the installation:

```python
import mypackage
print(mypackage.__version__)
```

## Quickstart

```python
from mypackage import MySimulator

sim = MySimulator(config="default.yaml")
results = sim.run()
```

## Documentation

Full documentation: [Read the Docs link]

## Citation

Please cite this software using the CITATION.cff file.

## License

MIT License

Regla 5: Incluya un comando de ayuda para CLIS

Si su software tiene una interfaz de línea de comandos, incluya un indicador claro --help. Debe explicar los comandos, los argumentos requeridos, los parámetros opcionales y los ejemplos.

Las herramientas de Python como argparse hacen que esto sea sencillo.

Regla 6: Control de versiones de su documentación

Guarde la documentación junto con el código en el control de versiones. Los usuarios de versiones de software anteriores necesitan acceso a la documentación que coincida con esas versiones.

Utilice el alojamiento de documentación con versiones cuando sea posible para que los usuarios puedan cambiar entre versiones.

Regla 7: Documente su API

Documente funciones públicas, clases, argumentos, valores de retorno y excepciones. Utilice un estilo de docString consistente para que las herramientas automatizadas puedan generar documentación de API legible.

Ejemplo:

def run_simulation(config_path, steps):
    """Run the simulation from a configuration file.

    Args:
        config_path: Path to the YAML configuration file.
        steps: Number of time steps to run.

    Returns:
        Simulation results object with fields, metadata, and diagnostics.

    Raises:
        ValueError: If the configuration file is invalid.
    """
    ...

Regla 8: Usar herramientas de documentación automatizada

No escriba todo manualmente si las herramientas pueden generar parte de él. Las herramientas de documentación automatizadas reducen el trabajo repetitivo y mantienen la documentación más cerca del código.

Las herramientas útiles incluyen:

• Sphinx para paquetes de Python con API complejas.
• mkdocs para sitios de documentación simples basados en rebajas.
• Lea los documentos para el alojamiento y las compilaciones de documentación automática.

Regla 9: Escribir mensajes de error procesables

Los buenos mensajes de error le dicen a los usuarios qué salió mal, por qué sucedió y cómo solucionarlo.

# Bad
raise ValueError("Invalid input")

# Good
raise ValueError(
    f"Input parameter 'temperature' must be between 0 and 3000 K. "
    f"Received {temperature} K. Check your simulation config file."
)

Esto ahorra tiempo de depuración y reduce las solicitudes de soporte.

Regla 10: Dile a la gente cómo citar tu software

Si desea que su software de investigación reciba crédito, proporcione instrucciones de cita. Incluya un archivo DOI, BibTex y CITATION.cff.

Si el software no tiene una publicación de revista, use Zenodo para acuñar un DOI para las versiones. Enviar al software Journal of Open Source también puede hacer que el software sea más fácil de citar.

Plantillas de documentación que puede usar hoy

El árbol de decisión de documentación

Antes de escribir documentación, haga tres preguntas:

1. ¿Para quién es? ¿Usuarios, desarrolladores, mantenedores, revisores o colaboradores?
2. ¿Qué quieren? ¿Ejecutar el software, modificarlo, entender el modelo o citarlo?
3. ¿Qué formato se ajusta a la necesidad? ¿Tutorial, guía de instrucciones, referencia, explicación, comentario en línea o página API?

Estas preguntas ayudan a evitar un error común: escribir un documento sobrecargado para cada audiencia.

El formato del archivo de cita

El archivo CITATION.cff es un archivo legible por máquina y legible por humanos para la cita de software. Puede incluir:

• Nombre y versión del software.
• autores y afiliaciones.
• doi para el software.
• Información de Bibtex.
• URL del repositorio.

Cuando se combina con un Zenodo doi, CITATION.cff se convierte en un registro de citas estable para su software.

Ejemplo Citation.cff plantilla

cff-version: 1.2.0
message: "If you use this software, please cite it as below."
title: "Project Name"
version: "1.0.0"
doi: "10.5281/zenodo.xxxxxxx"
authors:
  - family-names: "Surname"
    given-names: "First Name"
    affiliation: "Research Institution"
repository-code: "https://github.com/username/project-name"
license: "MIT"

Herramientas del comercio

Errores comunes y cómo evitarlos

Error 1: Tratar todo como un Léame

Un Léame no puede hacer bien todos los trabajos. Si combina tutoriales, referencia, explicación, detalles de la API y la solución de problemas en un archivo, los usuarios tienen dificultades para encontrar lo que necesitan.

Separe la documentación por propósito utilizando los cuadrantes de Diátaxis.

Error 2: Escribir explicación en tutoriales

Los tutoriales deben ser breves, prácticos y lineales. Si un principiante debe entender el modelo matemático antes de usar el software, ponga esa explicación en una página separada y enlace.

Error 3: no la documentación que controla la versión

Si cambia un parámetro predeterminado en la versión 2.0, los usuarios de la versión 1.5 necesitan la documentación anterior. Los documentos versionados evitan la confusión y hacen que las versiones anteriores sean más utilizables.

Error 4: Suponiendo que el futuro lo recordarás todo

Es posible que no recuerde sus decisiones de diseño seis meses después. Las páginas de comentarios y explicaciones sirven como un cuaderno de laboratorio para sus opciones de implementación.

Error 5: Olvidar las instrucciones de la cita

El software sin guía de citas a menudo recibe menos crédito. Incluya un archivo DOI, Bibtex y CITATION.cff para que los usuarios sepan exactamente cómo citar su trabajo.

Un flujo de trabajo de documentación práctica

Puede implementar la documentación 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.

Fase 1: antes de escribir cualquier código

1. Cree un archivo CITATION.cff de borrador.
2. Elabore un archivo Léame esqueleto con el propósito del proyecto, el marcador de posición de la instalación y la licencia.
3. Decida si la audiencia principal son los usuarios, desarrolladores, mantenedores o los tres.

Fase 2: Durante el desarrollo

1. Escriba los comentarios mientras codifica, especialmente para las opciones algorítmicas.
2. Agregue docStrings para cada función y clase pública.
3. Configure Sphinx o mkdocs antes de tiempo para que la documentación se construya junto con el código.
4. Agregue ejemplos cuando las características se vuelvan estables.

Fase 3: Después del desarrollo

1. Escriba una guía de inicio rápido.
2. Complete el Léame con las instrucciones de instalación, uso, licencia y cita.
3. Escriba al menos una guía práctica para el caso de uso más común.
4. Cree o actualice el DOI a través de Zenodo, Joss u otra ruta de publicación adecuada.

Enlaces internos y guías relacionadas

Para temas relacionados en flujos de trabajo de simulación científica:

• Mejores prácticas de documentación para paquetes científicos de Python — Herramientas y documentación específicas de Python estructura.
• Integración continua para software de investigación — CI/CD para pruebas y validaciones automatizadas.
• lectura y comprensión de la documentación de Fipy — Patrones prácticos de documentación de Fipy.
• Flujos de trabajo de investigación reproducibles: Docker y conda — Entorno reproducibilidad.
• Mejores prácticas para mantener el código científico — Mantenimiento de proyectos a largo plazo.

Resumen y próximos pasos

La documentación transforma el código de un artefacto experimental frágil en un activo de investigación duradero. El marco de diátaxis da estructura. Las diez reglas simples dan una lista de verificación práctica. Las plantillas y las herramientas proporcionan un punto de partida rápido.

Comience con un pequeño paso: cree un archivo CITATION.cff y agregue la guía de citación. Esto hace que el software sea más fácil de citar y de crédito.

A continuación, agregue un Léame con enlaces de instalación, inicio rápido, licencia y documentación. Este es el documento más impactante para la usabilidad.

A continuación, documente la API con docStrings consistentes y configure Sphinx o MKDocs. Esto ayuda a los usuarios y futuros mantenedores a comprender cómo funciona el código.

Finalmente, escriba al menos una guía de instrucciones para el caso de uso más común. Esa es a menudo la página que los colaboradores realmente necesitan.

Cada pieza de documentación hace que su software esté un paso más cerca de la investigación reproducible.

Referencias y lectura adicional

• Lee, B.D. (2018). Diez reglas simples para documentar software científico. PLOS Biología computacional, 14(12): E1006561. doi: 10.1371/journal.pcbi.1006561
• Instituto de Sostenibilidad de Software. ¿Cuáles son las mejores prácticas para la documentación de software de investigación? source
• Procida, D. Diátaxis: un enfoque sistemático de la creación de documentación técnica. fuente
• Wilson, G., et al. (2014). Mejores prácticas para la computación científica. PLOS Biology, 12(1): E1001745. doi: 10.1371/journal.pbio.1001745
• Revista de software de código abierto. fuente
• Lea los documentos. fuente

¿Necesita ayuda para estructurar la documentación para su proyecto de simulación?

Si su equipo de investigación necesita ayuda para configurar las canalizaciones de documentación automatizada, diseñar una estructura de documentación que cumpla con la diátaxis o integrar la documentación en los flujos de trabajo de CI/CD, nuestros expertos en ciencias computacionales pueden ayudarlo.

Contáctenos a través de nuestro sistema de seguimiento de problemas para discutir las necesidades de documentación de su proyecto.