Cómo escribir informes técnicos y no morir en el intento (I)

En esta vida hay cosas que nunca nos apetece hacer: bajar la basura, hacer dieta, una colonoscopia un lunes en ayunas… En el mundo TIC esos “no apetece” son a veces ligeramente diferentes. Sería realmente curioso saber los resultados de esta encuesta.

Elige por orden de preferencia las siguientes actividades:

1. Realizar una presentación ante tu jefe y el jefe de tu jefe.
2. Documentar con detalle un código/sistema que estás a punto de desplegar.
3. Realizar un informe técnico de 50+ páginas.
4. Pelear en pelotas contra un oso armado con un mondadientes.

En muchos casos el personal técnico es justamente eso: técnico. No vamos a entrar en el cliché de “toda la gente que trabaja en tecnología son unos frikis”, pero sí que hay que reconocer que a los técnicos nos suele gustar más cacharrear, desarrollar, crear cosas… que tener que contarlas.

Existe, sin embargo, una cruda realidad; la calidad de vuestro trabajo va ser el máximo de dos factores: vuestra capacidad técnica REAL y vuestra capacidad técnica PERCIBIDA. Es decir, podéis ser técnicamente excelentes, pero si vuestros jefes no perciben esa calidad… es un problema. Una presentación, una documentación o un informe son en realidad una extensión de vuestras capacidades, y de ahí la necesidad de desarrollarlas como medio de avance profesional.

El cómo presentar dignamente merecería una serie completa de artículos, así que vamos limitarnos a recomendaros varios recursos de calidad:

• Presentaciones artesanas: Tienen un par de libros estupendos, y un mini curso en SlideShare que es oro puro. Altamente recomendables.
• El arte de presentar: Tienen unos cursos presenciales de cómo hacer presentaciones excelentes, y un libro avanzado espectacular.
• Nancy Duarte: Es una jefa de las presentaciones. Sus libros Slide:ology, Resonate e Illuminate son la santísima trinidad sajona de cómo hacer presentaciones like a boss.

La documentación de código/sistemas es un ámbito a veces tan específico que no tenemos recursos sólidos que recomendaros. Si alguien tiene documentación sobre cómo documentar en condiciones (valga la redundancia), será más que bien recibida en los comentarios.

Pasemos entonces a cómo realizar informes técnicos, tarea para la cual hemos recopilado una buena cantidad de consejos y trucos, estructurados en cuatro categorías:

1. Consejos estratégicos: notas de alto nivel sobre cómo afrontar crear un informe técnico.
2. Consejos de estructura: cómo estructurar tu informe técnico.
3. Consejos de redacción: cómo redactar tu informe técnico de forma profesional.
4. Consejos espirituales: un pequeño cajón de sastre sobre cómo mejorar tus capacidades.

Es obligatorio dar el mérito correspondiente a Lenny Zeltser (@LennyZeltser), que con su cheatsheet de consejos sobre cómo escribir informes (que compartimos al 95%) han ayudado a cristalizar este HowTo (y dicho sea de paso, tiene unos materiales sobre análisis de malware excelentes). Dicho esto, si tienes tu procesador de texto favorito abierto, tu CPU sin carga y un buen café… ¡empezamos!

Consejos estratégicos

Determina los objetivos del informe

Lo primero que debes hacer cuando escribes un informe técnico es determinar su función: qué es lo que queremos conseguir con el mismo, cuáles son los objetivos a alcanzar.

Puede ser explicar un incidente de seguridad (profundizaremos más en esa subcategoría), realizar un análisis de pros y contras de una tecnología o algo tan simple como mostrar el estado de un proyecto.

Sea cual sea, tienes que ser capaz de condensar el objetivo del informe en una línea de texto, y usar esa línea de texto como una regla básica en la redacción del documento: si lo que escribes no está directamente alineado con esos objetivos, probablemente no sea necesario.

Ejemplos:

• Definir la respuesta llevada a cabo respecto al incidente de seguridad PI-0023.
• Establecer los requisitos de seguridad de la arquitectura de XXX.
• Decidir si emplear la tecnología X o Y en el proyecto Z.

Consejo 1: Define el objetivo del informe; Concrétalo para que ocupe una línea de texto.

Identifica a tu audiencia

Casi tan importante como saber lo que tienes que contar es conocer a quién se lo tienes que contar. Nuestros informes pueden estar dirigidos a diversos tipos de perfiles, y cada uno tiene su propia cultura y necesidades. Saber identificar el destinatario de nuestro informe y adaptar nuestro mensaje al mismo hará que llegue más fácil e incrementará su eficacia.

Ejemplos:

• Técnicos: querrán más detalles técnicos, y se fijarán más en la solidez de las decisiones técnicas tomadas.
• Directivos: querrán más detalles de todo relacionado con costes y plazos, y se centrarán en las ventajas competitivas.
• Legal: querrán más detalles de posibles normativas/leyes implicadas, y se centrarán en las posibles consecuencias legales del informe.

Consejo 2: Identifica quiénes va a leer tu informe, y redacta el documento con ello en mente.

KISS (Keep it Simple, Stupid)

Este es un consejo de doble filo: en algunas organizaciones se valora la calidad de un informe y el trabajo que ha costado en función de las páginas que ocupa (lo que se llama cariñosamente “calificar el informe al peso”).

Sin embargo, la realidad es que muchos jefes no quieren (ni tampoco tienen tiempo) de leerse 200 páginas de prosa rimbombante con abundante relleno que engorda el informe cual pienso para un cochino. ¿Para qué sí que van a tener tiempo? Para leerse un informe de 20 páginas en el que se explique de forma clara y concisa el objeto del informe.

Ejemplo: Informe de un incidente dirigido al responsable de seguridad (v1)

Los atacantes hicieron uso de una vulnerabilidad 0-day (fallo de seguridad no reconocido por el fabricante para el que no hay parche conocido) para realizar un ataque de DDoS (Distributed Denial of Service, ataque de denegación de servicio distribuida) para agotar los recursos de CPU de los 16 frontales web del cluster de VMWare PEPITO (situado en las instalaciones de Mordor, Carretera Lorien 21), obligando a los técnicos a realizar un esfuerzo adicional y entrar por la VPN SSL ofrecida por el software F35-B en su versión 2.2.2.1 para realizar un inventario pormenorizado del estado de los servidores y reiniciar mediante IPMI los servidores 2,3 y 5.

En este caso la audiencia es un perfil técnico: si tenéis que explicarle al CISO de vuestra organización qué es un DDoS o un 0-day, estamos buenos. Y a menos que la versión de VPN empleada tenga algo que ver con el incidente, tampoco es necesario incluirla (en todo caso, iría en los anexos como veremos cuando hablemos de cómo estructurar un informe).

Ejemplo: Informe de un incidente dirigido al responsable de seguridad (v2)

Los atacantes emplearon un 0-day para realizar un DDoS contra los frontales web del clúster PEPITO. Los técnicos tuvieron que reiniciar los servidores 2,3 y 5.

Como veis, si vamos al grano y nos centramos en lo importante pasamos de 8 líneas a 2. Ahorramos tiempo en la redacción del informe, hacemos felices a nuestros jefes y salvamos árboles del Amazonas (por desgracia, a día de hoy todavía se imprimen muchos documentos)

Consejo 3: Sé conciso y claro. Si crees que algo no hace falta, elimínalo o muévelo a los anexos.

Ofrece valor

Todo informe realizado debe aportar algo que ayude a resolver el problema presente. Analiza el contenido de tu informe y pregúntate: ¿Qué valor estoy aportando con este documento? Es muy importante identificar el valor que aportamos con ese documento y resaltarlo debidamente en los lugares adecuados (resumen ejecutivo, conclusiones, etc…)

Ejemplo: La optimización de las reglas YARA en función de su tasa de falsos positivos y su necesidad real ha permitido eliminar 100 reglas, reduciendo en un 20% la tasa de falsos positivos de la plataforma de seguridad.

Consejo 4: Identifica el valor aportado en tu documento y dale visibilidad.

[UPDATE 25 de febrero: Para satisfacer mi curiosidad hice una encuesta rápida en Twitter, y aquí tenéis los resultados que confirman mi teoría…]