Piensa en quién recibe
Una entrega debe funcionar para alguien que no siguió las conversaciones del proyecto. Explica el objetivo, lo que existe, cómo ejecutarlo y cómo reconocer el resultado esperado. Evita depender de frases como “es solo hacerlo como antes”.
Elige un proyecto pequeño, como la central de pedidos, y prepara tu kit. El destinatario debe poder ubicar los archivos y entender las limitaciones sin tener que leer todo el historial. El README funciona como puerta de entrada, no como un depósito de todas las anotaciones.
Por qué aprender
La calidad de la entrega determina el costo de la continuidad. Una herramienta útil pierde valor cuando solo su autor sabe cómo iniciar, probar o actualizar.
✓ Hacer
Probar los pasos del README en un contexto limpio.
✗ Evitar
Publica todos los archivos de la carpeta sin revisar.
Conceptos clave
Organiza el material por función
Separa código, ejemplos, documentación y evidencias. Usa nombres descriptivos y rutas consistentes. Los documentos de trabajo privados, credenciales y materiales que no pertenecen a la distribución deben quedar fuera del conjunto publicado.
Una carpeta de evidencias puede contener el resultado de las pruebas y capturas de estados importantes. No hace falta guardar cada archivo temporal. Elige lo que demuestra el comportamiento y explica cómo se produjo, para que la verificación pueda repetirse.
Por qué aprender
La organización por función reduce el tiempo de búsqueda y evita mezclar ejemplos con datos reales. También hace más simple la revisión del conjunto que se va a publicar.
Un camino para aplicar
- Organiza los archivos y escribe la puerta de entrada.
- Ejecuta las instrucciones con los ejemplos proporcionados.
- Revisa la distribución y entrega contexto de continuidad.
Conceptos clave
Escribe instrucciones ejecutables
Lista prerequisitos, comando de inicio y una acción de prueba. Ejecuta exactamente las instrucciones en una carpeta limpia o en un contexto equivalente. Si un paso depende de algo instalado globalmente, registra esa dependencia.
Evita instrucciones que prometen una automatización inexistente. Si la tarea exige una decisión manual, explica el criterio. El lector debe saber qué esperar después de cada etapa y cómo reconocer un error común sin tener que adivinar.
Por qué aprender
Una instrucción solo está validada cuando se siguió. Esta prueba revela archivos ausentes, dependencias ocultas y nombres de rutas que solo funcionan en la computadora de quien escribió.
projeto/
README.md
src/
exemplos/entrada.csv
docs/arquitetura.md
docs/decisoes.md
evidencias/verificacao.md
CHANGELOG.md
# Antes de publicar:
git status --short
git diff --cached --stat
Conceptos clave
Arma una base de conocimiento pequeña
Elige los documentos que explican el proyecto y registra tema, versión y ubicación. Un índice de diez elementos es suficiente para empezar. La base puede alimentar un dosier, pero necesita mantener el vínculo entre la respuesta y el documento.
Cuando un archivo cambie, revisa los resúmenes que dependen de él. Una base “viva” no significa generar contenido sin parar; significa tener una rutina de actualización con responsable, frecuencia y criterio de cambio. Marca los materiales desactualizados en vez de dejarlos competir con la versión actual.
Por qué aprender
Una base organizada preserva decisiones y reduce preguntas repetidas. El control de actualización evita que respuestas antiguas parezcan actuales solo porque siguen siendo fáciles de encontrar.
✓ Hacer
Mantener ejemplos ficticios separados de datos privados.
✗ Evitar
Documentar una función que todavía no existe.
Conceptos clave
Haz una revisión de la publicación
Antes de versionar, revisa el conjunto exacto de archivos. Un ignore evita agregar archivos nuevos no deseados, pero no elimina automáticamente los que ya se han rastreado. Revisa el estado y el contenido preparado para el commit.
Después de publicar, prueba los enlaces y los archivos que deben abrirse. Registra la versión entregada y los próximos pasos. El resultado de la publicación es un punto de referencia para el mantenimiento, y no el fin de la necesidad de verificar cambios futuros.
Por qué aprender
La revisión evita distribuir material privado o una versión incompleta. La identificación de la entrega permite relacionar documentación, código y resultados de prueba.
| Criterio | Evidencia esperada |
|---|---|
| Reproducción | Otra persona puede ejecutar el ejemplo. |
| Coherencia | README, mapa y código describen la misma versión. |
| Continuidad | Se identifican las limitaciones y el próximo paso. |
Conceptos clave
Práctica: entrega para un segundo lector
Arma el kit de la central de pedidos o de otro proyecto pequeño. Pide que una persona siga el README, abra el diagrama, ejecute el ejemplo y encuentre una limitación conocida. Si estás estudiando solo, repite los pasos en una carpeta nueva.
Registra dónde hubo dudas y ajusta la parte mínima necesaria. Al final, escribe un resumen de continuidad con el estado actual, decisiones y la próxima tarea. El kit está completo cuando permite usar y continuar el proyecto sin depender de la conversación que lo creó.
Por qué aprender
Esta práctica cierra el curso conectando implementación y mantenimiento. Pasas de una respuesta producida por IA a una entrega que se puede verificar, compartir y mejorar.
Tu ejercicio
Prepara un kit con README, ejemplo de entrada, salida esperada, mapa del flujo y registro de verificación. Haz una revisión de los archivos que se compartirán.
Descargar ficha de la prácticaRevisar respuesta comentada
El README apunta a los demás documentos y contiene pasos probados. La entrada usa datos ficticios; la salida permite comprobar las reglas. El mapa corresponde al flujo implementado. La verificación informa el resultado y las limitaciones, y el próximo paso describe una única mejora delimitada.
Comprueba tu comprensión
¿Agregar una carpeta al .gitignore elimina los archivos que ya están rastreados?
Conceptos clave
Lo que queda de este módulo
Un kit de entrega con instrucciones, mapa, evidencias y próximos pasos.
- ✓ Otra persona puede ejecutar el ejemplo.
- ✓ README, mapa y código describen la misma versión.
- ✓ Las limitaciones y el próximo paso están identificados.
El progreso registra tu lectura. La práctica queda concluida cuando revisas la entrega.