Documentación para desarrolladores: Guía de campo de un ingeniero sobre redacción técnica

1. Primeros pasos

2. Investigación de la documentación

1. Comprensión de los usuarios

2. Cultivar la empatía

3. Comprender los deseos del usuario, las necesidades del usuario y las necesidades de la empresa

4. Reclutamiento de usuarios para la investigación

3. Métodos de investigación

1. Lectura de comentarios de código

2. Ponerlo a prueba

Registros de fricción

3. Realización de grupos focales y entrevistas diversos e inclusivos

4. Mapeo del recorrido del usuario

4. Identificación y trabajo con los interesados

1. Encontrar a sus expertos

2. Desarrollo colaborativo de la documentación

5. Aprender del contenido existente

1. El valor de los documentos de diseño

2. Encontrar ejemplos en la industria

Diseño de la documentación

1. Definición del conjunto inicial de contenido

2. Decidir la documentación mínima viable

3. Elaboración de criterios de prueba y aceptación

Comprensión de los tipos de contenido

Conceptos, tutoriales y documentación de referencia

Comentarios del código

Especificaciones de la API

READMEs

Guías

Notas de la versión

Redacción de la documentación

1. Prepararse para el éxito de la escritura

2. ¿Para quién es esto? Personas, requisitos, tipos de contenido

3. Definición de "terminado"

4. Cómo iterar

Herramientas y consejos para escribir borradores

1. Comprender sus necesidades

2. Elegir sus herramientas de escritura (escritura a mano, solo texto, herramientas de escritura de productividad/medición)

3. "Trucos" para empezar a redactar contenido

Mecánica

Encabezados

Párrafos

Listas

Notas y advertencias

Conclusiones/pruebas

Uso de plantillas para formar borradores

1. Propósito de una plantilla

2. Cómo derivar una plantilla de documentos existentes

Cómo llevar las plantillas al texto

Recopilación de comentarios iniciales

Métodos de retroalimentación

Integración de la retroalimentación

Obtención de comentarios de colaboradores difíciles

Edición de contenido para publicación

1. Determinar el destino

2. Herramientas de edición (Grammarly, linters, etc.)

3. Declarar "suficientemente bueno"

Recapitulación, estrategias y tranquilidad

Estructuración de conjuntos de documentación

1. Dónde viven los tipos de contenido

2. Conceptos, tutoriales y documentación de referencia

3. Comentarios del código

4. Especificaciones de la API

READMEs

5. Guías

6. Notas de la versión

Diseño de su arquitectura de información

1. Estilos de arquitectura de información de contenido

2. Diseño para la búsqueda

3. Creación de rutas claras y bien iluminadas a través del contenido

Pruebas de usuario y mantenimiento

Planificación de la automatización de documentos

Integración de ejemplos de código y contenido visual

1. Integración de ejemplos de código

2. Cuándo y por qué usar ejemplos de código

3. Creación de muestras concisas, utilizables y mantenibles

4. Estandarización de sus muestras

Uso de contenido visual: Capturas de pantalla, diagramas y videos

1. Cuando su documentación pueda necesitar contenido visual

2. Hacer que su contenido visual sea accesible

3. Integración de capturas de pantalla, diagramas

4. Videos

Medición del éxito de la documentación

Cómo tiene éxito la documentación

Medición de diferentes tipos de calidad de la documentación

1. Calidad estructural

2. Calidad funcional

3. Calidad del proceso

Medir lo que quieres cambiar

Conclusiones

Autor: Jared Bhatti, Zachary Sarah Corleissen, Jen Lambourne
Editorial: Apress
Publicado: 10/09/2021
Páginas: 240
Tipo de encuadernación: Tapa blanda
Peso: 0.79 libras
Tamaño: 9.21 pulgadas (alto) x 6.14 pulgadas (ancho) x 0.53 pulgadas (profundidad)
ISBN13: 9781484272169
ISBN10: 1484272161
Categorías BISAC:
- Informática | Internet | Programación web
- Informática | Programación | Código abierto

Acerca del autor

Jared Bhatti

Jared es un escritor técnico sénior en Alphabet y cofundador del equipo de documentación de Google Cloud. Ha trabajado durante los últimos 14 años documentando una variedad de proyectos en Alphabet, incluidos Kubernetes, App Engine, Adsense, los centros de datos de Google y los esfuerzos de sostenibilidad ambiental de Google. Actualmente dirige la documentación técnica en Waymo y asesora a varios escritores junior en la industria.

Zachary Sarah Corleissen

Zach comenzó este libro como el escritor técnico principal de la Linux Foundation y lo terminó como el primer escritor técnico sénior de Stripe. Zach fue copresidente de la documentación de Kubernetes desde 2017 hasta 2021, y ha trabajado anteriormente en la documentación para desarrolladores en GitHub, Rackspace y varias startups. Disfrutan hablando en conferencias y les encanta asesorar a escritores y oradores de todas las habilidades y orígenes.

Heidi Waterhouse

Heidi pasó un par de décadas en Microsoft, Dell Software y muchas, muchas startups aprendiendo a comunicarse con y para desarrolladores. Actualmente trabaja como defensora principal de desarrolladores en LaunchDarkly, pero se sintió aliviada al descubrir que la comunicación técnica es universal en todos los roles.

David Nunez

David dirige la organización de escritura técnica en Stripe, donde fundó el equipo de documentación interna y escribió para la revista Increment. Antes de Stripe, fundó y dirigió la organización de escritura técnica en Uber y ocupó un puesto de liderazgo en documentación en Salesforce. Después de haber dirigido equipos que han escrito sobre la nube, infraestructura propia, camiones autónomos e infraestructura económica, ha estudiado las muchas formas en que la documentación técnica puede moldear la experiencia del usuario. David también actúa como asesor para varias startups en el espacio de las plataformas de conocimiento.

Jen Lambourne

Jen lidera la disciplina de escritura técnica y gestión del conocimiento en Monzo Bank. Antes de su incursión en las fintech, dirigió una comunidad de documentaristas en todo el gobierno del Reino Unido como Jefa de Redacción Técnica en el Government Digital Service (GDS). Habiendo pasado del gobierno a las finanzas, reconoce que se siente atraída por la creación de contenido inclusivo y centrado en el usuario en industrias tradicionalmente hostiles. Le gusta usar herramientas para desarrolladores para gestionar documentos, desmitificar el proceso de escritura para ingenieros, asesorar a escritores junior y presentar sus aventuras en documentación en conferencias.