¡Crea y mantiene rápidamente documentación sobre tu código o las funciones que has desarrollado!

Descubre cómo Alex utilizó Docs para permitir que su equipo mejorara las funciones más rápidamente.

Conoce a Alex

Alex es un desarrollador senior en una empresa de software basada en la nube. Descubren que algunas funciones tienen documentación muy limitada.

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

El desafío

Los equipos de producto e ingeniería trabajan en un calendario muy ajustado para lanzar funciones en el producto. Los desarrolladores tienen muy poco tiempo para poder 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 nuevos se sienten frustrados por la falta de documentación. Les resulta difícil conocer el producto con eficacia.

Otros desarrolladores sienten que pasan más tiempo respondiendo preguntas en lugar de resolver problemas y escribir mejor código.

La solución

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

Crea la estructura del documento y la página

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

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

Alex crea algunas páginas dentro del documento para estructurar el contenido basado en lo que el equipo necesita saber y 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 control de calidad

7. Preguntas frecuentes y solución de problemas

Consejo: ¡Busca páginas o contenido específico dentro de un documento utilizando la función de búsqueda!

Encabezados

En cada página, Alex configura títulos para que quede claro al equipo de desarrollo qué información debe ir en cada lugar.

Resumen del producto

• Resumen del producto

• Resumen de la función

• Casos de uso

• Diseño de interfaz de usuario

Front End

• Elementos de la interfaz

• Estilos

• Descripciones emergentes

Back End

• Rutas de API

• Esquema de base de datos

Móvil

• iOS

• Android

Pruebas y control de calidad

• Criterios de aceptación

• Pruebas automatizadas de QA

Formato

Alex utiliza una combinación de las opciones de formato disponibles en los Documentos de ClickUp para dar a su documentación un aspecto y sensación consistentes.

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

Alex utiliza acentos graves ( `` ) para formatear texto como código en línea y mostrar líneas individuales de código, como se muestra en el ejemplo a continuación:

Para fragmentos de código más grandes, Alex utiliza Formato de Bloque de Código ( /co ) como se muestra a continuación:

Opciones de formato de bloque de código

Configura tu bloque de código para usar el lenguaje de programación que prefieras.

1. Pasa el cursor sobre la esquina superior derecha

2. Selecciona tu idioma preferido

Vincula e incrusta contenido

Ahora el documento de Alex tiene texto, algunas capturas de pantalla y fragmentos de código útiles.

Se ve bien, pero el Resumen del Producto sigue vacío.

El equipo de producto utiliza Figma para diseñar y crear el esquema de la interfaz de usuario. Alex utiliza el comando de barra inclinada /figma para incorporar el diseño actualizado de la función directamente en la página de Resumen del Producto.

Alex usa la mención @@ para vincular a la tarea épica en la hoja de ruta del equipo.

Crea una plantilla

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

1. Haz clic en el ícono de ajustes del documento en la barra lateral derecha

2. Selecciona Guardar como plantilla

Alex completa un documento de ejemplo utilizando la plantilla para que el equipo tenga un estándar de oro de documentación 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 próxima reunión de equipo. A los otros desarrolladores les encanta el ejemplo detallado de documentación de Alex.

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

El equipo decide sobre una función. Alex crea un documento, aplica la plantilla usando el comando de barra inclinada /temp y comparte el enlace con todos los participantes en la llamada.

Unos cuantos desarrolladores se incorporan y empiezan a editar el Doc en colaboración con Alex. Todos rellenan las páginas y secciones con las que están más familiarizados.

Todo el equipo queda gratamente sorprendido cuando, después de solo 20 minutos, han creado un borrador bastante completo de la documentación.

El resultado

El equipo acepta probar la plantilla y la documentación de Alex. En su siguiente Sprint, unos cuantos desarrolladores dedican 30 minutos a rellenar la documentación de la función estrella.

La documentación aún no está completa. Hay un esquema básico con suficiente detalle para ayudar a otros desarrolladores a comenzar a entender y mejorar la función.

Después de unas semanas, el hábito de escribir documentación se ha convertido en una parte importante de las funciones del equipo de ingeniería.

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

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 experimentados notan menos preguntas de sus colegas 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".