¡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.

Conozca 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 cantidad 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 con un calendario muy ajustado para lanzar nuevas funciones en el producto. Los desarrolladores disponen de 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 novatos están frustrados por la falta de documentación. Les resulta difícil aprender sobre el producto de manera efectiva.

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

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 el documento y la estructura de la página

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

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

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 QA

7. Preguntas frecuentes y solución de problemas

Consejo: ¡Busca páginas específicas o contenido dentro de un Documento utilizando la función de Búsqueda!

Títulos

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

Resumen del producto

• Brief de producto

• Resumen de la función

• Casos de uso

• Diseño de interfaz de usuario

Front End

• Elementos de IU

• Estilos

• Descripciones emergentes

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 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. Seleccionando tu idioma preferido

Vincular e incrustar contenido

Ahora el documento de Alex contiene 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 utiliza Figma para diseñar y crear prototipos de la interfaz de usuario. Alex utiliza el comando de barra inclinada /figma para integrar el diseño actualizado de la función directamente en la página de Resumen del Producto.

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

Crear una plantilla

Alex guarda el esquema del documento como una plantilla para que el equipo pueda crear rápidamente y de manera sencilla un documento con las subpáginas y títulos para otras funciones.

1. Haz clic en el icono 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 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 documentos al equipo de ingenieros en la siguiente reunión del 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 llevar completar los detalles. Alex les reta a elegir una función, para que demuestren 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 de la llamada.

Unos cuantos desarrolladores se unen y comienzan a editar colaborativamente el Documento con Alex. Cada uno completa las páginas y secciones que mejor conoce.

Todo el equipo se sorprende gratamente 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á 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 unas semanas, el hábito de redactar 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, se reduce el tiempo dedicado a crear y mantener la documentación.

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 por parte de sus colegas y equipos de soporte 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".