¡Crea y mantén documentación sobre tu código o las funciones que has desarrollado de manera rápida!

Descubre cómo Alex usó Documentos para ayudar a su equipo a mejorar funciones más rápido.

Conoce a Alex

Alex es un desarrollador sénior en una empresa de software basada en la nube. Descubre que algunas funciones tienen documentación muy limitada.

Alex nota que el equipo dedica buena parte de su tiempo a investigar cómo funcionan las características directamente desde el código del software. Esto ralentiza la capacidad del equipo para mejorar las funciones existentes.

El desafío

Los equipos de producto e ingeniería trabajan con un calendario muy ajustado para lanzar funciones al producto. Los desarrolladores tienen muy poco tiempo para crear documentación sobre las nuevas funciones.

El equipo no tiene tiempo para mantener la documentación a medida que una función mejora con el tiempo y se corrigen errores.

Algunos desarrolladores más nuevos están frustrados por la falta de documentación. Les resulta difícil aprender sobre el producto de forma efectiva.

Otros desarrolladores sienten que pasan más tiempo respondiendo preguntas que resolviendo problemas y escribiendo mejor código.

La solución

Alex está trabajando en mejorar una función que no tiene buena documentación. Decide crear un Documento de ClickUp con información sobre la función como material de referencia para otros desarrolladores.

Crear el Documento y la estructura de páginas

Alex decide que cada función debe tener su propio Documento. Cuando el equipo trabaja en una función, toda la información relevante queda en un único documento autónomo.

Usar páginas dentro de un Documento le permite al equipo encontrar respuestas rápidamente, sin tener que buscar y revisar Documentos separados.

Alex crea algunas páginas dentro del Documento para estructurar el contenido según lo que el equipo necesita saber y lo que podría estar buscando.

1. Resumen del producto
2. Código de front end
3. Código de back end
4. Infraestructura
5. Aplicación móvil
6. Pruebas y QA
7. Preguntas frecuentes y solución de problemas

Encabezados

En cada página, Alex configura encabezados para que el equipo de desarrollo tenga claro qué información va en cada sección.

Resumen del producto

• Resumen del producto
• Descripción de la función
• Casos de uso
• Diseño de interfaz

Front end

• Elementos de interfaz
• Estilos
• Tooltips

Back end

• Rutas de API
• Esquema de base de datos

Móvil

• iOS
• Android

Pruebas y QA

• Criterios de aceptación
• Pruebas automatizadas de QA

Formato

Alex combina las opciones de formato disponibles en Documentos de ClickUp para darle a su documentación una apariencia consistente.

Código en línea y bloques de código

Alex usa acentos graves ( ` ) para dar formato al texto como código en línea y mostrar líneas individuales de código, como se ve en el ejemplo a continuación:

Para fragmentos de código más extensos, Alex usa el formato de bloque de código ( /co ) como se muestra a continuación:

Opciones de formato del bloque de código

¡Configura tu bloque de código con el lenguaje de programación que prefieras!

1. Coloca el cursor sobre la esquina superior derecha
2. Selecciona tu lenguaje preferido

Vincular e insertar contenido

El Documento de Alex ya tiene texto, algunas capturas de pantalla y fragmentos de código útiles.

Se ve bien, pero el Resumen del producto todavía está vacío.

El equipo de producto usa Figma para diseñar y crear prototipos de la interfaz de usuario. Alex usa el comando de barra diagonal /figma para insertar el diseño actualizado de la función directamente en la página de Resumen del producto.

Alex usa la mención @@ para vincular la tarea de Epic en el cronograma del equipo.

Crear una plantilla

Alex guarda el esquema del Documento como una Plantilla para que el equipo pueda crear fácilmente un Documento con las subpáginas y encabezados para otras funciones.

1. Haz clic en el ícono de configuración del Documento en la barra lateral derecha
2. Selecciona Guardar como plantilla

Alex completa un Documento de ejemplo usando la plantilla para que el equipo tenga un estándar de referencia que usar como ejemplo.

Alex crea un nuevo Documento basado en la plantilla, lo completa y lo comparte con el equipo.

Prueba de concepto

Alex presenta el concepto de plantilla de Documento al equipo de ingeniería en la siguiente reunión del equipo. ¡A los demás desarrolladores les encanta el ejemplo detallado de documentación de Alex!

El equipo está preocupado por el tiempo que podría llevar completar los detalles. Alex los desafía a elegir una función para demostrarle a todos lo rápido que es crear documentación.

El equipo elige una función. Alex crea un Documento, aplica la plantilla con el comando de barra diagonal /temp y comparte el enlace con todos en la llamada.

Varios desarrolladores se unen y empiezan a editar el Documento de forma colaborativa con Alex. Cada uno completa las páginas y secciones con las que está más familiarizado.

Todo el equipo se lleva una grata sorpresa cuando, después de apenas 20 minutos, han creado un borrador bastante completo de documentación.

El resultado

El equipo decide darle una oportunidad a la plantilla y la documentación de Alex. En su siguiente Sprint, algunos desarrolladores dedican 30 minutos a completar la documentación de la función principal.

La documentación no está del todo terminada. Hay un esquema básico con suficiente detalle para ayudar a otros desarrolladores a empezar a entender y mejorar la función.

Después de algunas semanas, el hábito de escribir documentación se convierte en una parte importante de las responsabilidades del equipo de ingeniería.

Con algunos ajustes y mejoras a la plantilla de Alex, el tiempo dedicado a crear y mantener la documentación se reduce.

Alex envía una encuesta y descubre que:

• Los desarrolladores más nuevos se sienten más seguros trabajando con el código cuando hay documentación disponible
• Los desarrolladores con más experiencia reciben menos preguntas de sus colegas y de los equipos de soporte al cliente

¡Es un gran logro para el equipo de ingeniería! En un evento del equipo, Alex recibe el título honorario de "Bibliotecario residente y guardián del conocimiento".