¡Crea y mantén documentación sobre tu código o las funciones que has desarrollado de forma rápida!
Descubre cómo Alex utilizó 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 en la nube. Descubre que algunas funciones tienen documentación muy limitada.
Alex se da cuenta de que el equipo dedica una buena parte de su tiempo a investigar cómo funcionan las funciones directamente desde el código del software. Esto ralentiza la capacidad del equipo para mejorar las funciones existentes.
El reto
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 se mejora una función y se corrigen errores.
Algunos desarrolladores más nuevos están frustrados por la falta de documentación. Les cuesta aprender sobre el producto de forma eficaz.
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. Así, cuando el equipo trabaja en una función, toda la información relevante está en un único documento independiente.
Usar páginas dentro de un Documento permite al equipo encontrar respuestas rápidamente sin tener que buscar en Documentos separados.
Alex crea varias páginas dentro del Documento para estructurar el contenido según lo que el equipo necesita saber y lo que podría estar buscando.
- Resumen del producto
- Código de front end
- Código de back end
- Infraestructura
- Aplicación móvil
- Pruebas y QA
- Preguntas frecuentes y solución de problemas
Encabezados
En cada página, Alex añade encabezados para que el equipo de desarrollo tenga claro qué información va en cada apartado.
Resumen del producto
- Descripción del producto
- Esquema de la función
- Casos de uso
- Diseño de UI
Front end
- Elementos de UI
- 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 varias opciones de formato disponibles en ClickUp Documentos para dar a su documentación un aspecto uniforme y coherente.
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 de código individuales, como se muestra en el ejemplo a continuación:
Para fragmentos de código más extensos, Alex utiliza 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 para usar el lenguaje de programación que prefieras!
- Pasa el cursor por la esquina superior derecha
- Selecciona tu lenguaje preferido
Vincular e incrustar contenido
Ahora el Documento de Alex tiene texto, algunas capturas de pantalla y fragmentos de código útiles.
Tiene buena pinta, pero el Resumen del producto sigue vacío.
El equipo de producto usa Figma para diseñar y crear wireframes de la interfaz de usuario. Alex usa el comando de barra /figma para incrustar el diseño actualizado de la función directamente en la página de Resumen del producto.
Alex usa la mención @@ para enlazar con la tarea de Epic en el cronograma del equipo.
Crear una plantilla
Alex guarda el esquema del Documento como Plantilla para que el equipo pueda crear rápidamente un Documento con las subpáginas y los encabezados para otras funciones.
- Haz clic en el icono de ajustes del Documento en la barra lateral derecha
- Selecciona
Guardar como plantilla
Alex rellena un Documento de ejemplo con 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 rellena 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 de equipo. ¡Al resto de desarrolladores les encanta el detallado ejemplo de documentación de Alex!
Al equipo le preocupa el tiempo que podría llevar rellenar todos los detalles. Alex les reta a elegir una función para demostrar a todos lo rápido que es crear documentación.
El equipo se decide por una función. Alex crea un Documento, aplica la plantilla mediante el comando de barra /temp y comparte el enlace con todos los participantes en la llamada.
Varios desarrolladores se unen y empiezan a editar el Documento en colaboración con Alex. Cada uno rellena las páginas y secciones con las que está más familiarizado.
Todo el equipo se lleva una grata sorpresa cuando, tras apenas 20 minutos, han creado un borrador de documentación bastante completo.
El resultado
El equipo decide hacer una prueba con la plantilla y la documentación de Alex. En su próximo Sprint, varios desarrolladores dedican 30 minutos a rellenar la documentación de la función principal.
La documentación no está del todo terminada. Hay un esquema básico con el suficiente detalle para ayudar a otros desarrolladores a empezar a entender y mejorar la función.
Después de varias semanas, escribir documentación se ha convertido en una parte importante de las tareas 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 va reduciéndose.
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 experiencia reciben menos preguntas de sus compañeros y de los equipos de atención al cliente
¡Es un gran logro para el equipo de ingeniería! En un evento de equipo, Alex recibe el título honorífico de «Bibliotecario residente y guardián del conocimiento».