Documentación de Proyectos NET - código fuente

3 views

Skip to first unread message

Kiquenet

unread,

Mar 23, 2026, 11:26:46 AM (19 hours ago) Mar 23

to AltNet-Hispano

En un entorno corporativo con Microsoft M365: Excel, Word, Sharepoint

Desarrollo Azure Devops Repos GIT, ..

Recomiendan?

Documentación de los repos ( Azure Devops, proyectos, código) con Markdown (README.md) y en carpeta /docs (y subcarpeta /assets) en cada repo ?

Documentación común para todos los repos (por ejemplo, Entorno de trabajo.md, etcétarea)

Documentación en Word docx en Sharepoint para manual de usuario, guías, o algún otro documento no específico de repos ?

Qué uso dar a Mkdocs ?

grz

✅ Recomendación general (resumen ejecutivo)

En un entorno Microsoft M365 + Azure DevOps, lo más eficiente y sostenible suele ser:

1) Documentación técnica del repositorio → en Markdown

README.md (visión general)
Carpeta /docs y /assets (detalles técnicos)
Estructura homogénea en todos los repos

2) Documentación transversal → en SharePoint

Políticas, procesos, estándares internos
Guías corporativas y operativas
Documentos que requieren colaboración tradicional o flujos de aprobación

3) Manuales de usuario y guías de operación → Word / PDF en SharePoint

Para usuarios finales
Para auditores
Para áreas no técnicas

4) MkDocs → solo si queréis documentación navegable tipo portal

Ideal para:

Repos grandes
Documentación viva técnica
Un portal unificado de varios repos

1. “Carpeta /docs en cada repo” puede dispersar la información

Si tienes muchos repos pequeños, terminarás con documentación duplicada o contradictoria.
👉 Debilidad: no escala bien si hay mucho código distribuido.

2. Documentación en Word puede convertirse en un cuello de botella

Word es excelente para usuarios finales, pero:

No versiona igual que Git
No integra bien en pipelines 👉 Debilidad: no apto para documentación técnica viva.

3. Falta definir quién mantiene qué

El mayor riesgo no es la tecnología sino:

falta de ownership
actualización irregular
👉 Debilidad: sin roles claros, toda la estrategia falla.

1. “Todo debería estar en Markdown, incluso manuales de usuario”

Hay empresas que apuestan por 100% Markdown y generan los PDF con herramientas (Pandoc, MkDocs, DocFX).
✔ Ventaja: un único formato, versionado en Git.
✘ Problema: usuarios no técnicos pueden sentirse fuera.

2. “SharePoint no es necesario, DevOps Wiki es suficiente”

Azure DevOps Wiki es más rápido y versionado automáticamente.
✘ Pero: carece de control documental corporativo, flujos de aprobación, permisos matriciales, etc.
En entornos corporativos grandes SharePoint gana.

3. “MkDocs es sobreingeniería”

Si el equipo es pequeño, un README.md bien hecho puede ser suficiente.
MkDocs requiere: