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

Consejos de estructura

Define una estructura base
Si tu informe tiene una buena estructura va a ser mucho más fácil de redactar, y sobre todo de leer (recuerda que nuestro objetivo es el éxito del informe, así que toda ayuda es bienvenida). Una estructura básica válida para prácticamente cualquier tipo de documento podría ser esta:

• Resumen ejecutivo: es tan importante que tiene apartado propio
• Objeto y alcance: cuál es el objetivo del documento y hasta dónde vamos a llegar
• Antecedentes y consideraciones preliminares: todo aquello que debería conocerse de forma previa a la lectura de este informe
• Análisis: describir el trabajo realizado objeto del informe
• Conclusiones: a qué conclusiones llegamos con los análisis realizados.
• Anexos: toda la información adicional que queramos incluir

Consejo 5: Define una estructura base para tu contenido.

Define el resto de puntos del informe creando un índice

Una vez completada la estructura base, lo siguiente que tienes que hacer es pensar en cómo vas a estructurar el resto del documento. Una técnica excelente es la de “completa el índice”: crea el resto de puntos del documento y crea un índice vacío dentro de tu procesador de textos.

Puede parecer una tontería, pero una técnica muy efectiva para evaluar libros técnicos es a través de su índice: con un poco de práctica, de un vistazo puedes saber si un libro te puede interesar o no… y lo mismo sucede con muchos informes. El tener un buen índice ayuda a los lectores a localizar las partes que les interesan, y a vosotros a la hora de redactarlo ya que al final ya sabéis dónde tenéis que poner cada cosa, y tan solo es cuestión de ir “rellenando” los huecos.

Ejemplo (auditoria de seguridad)

1. Resumen ejecutivo
2. Objeto y alcance
   • Sistemas a auditar
   • Sistemas expresamente fuera del alcance
3. Antecedentes y consideraciones preliminares
   • Personal de contacto de cada entidad
   • Reglas particulares de la auditoria
   • Fechas de realización de la auditoria
4. Resultados de la auditoria
   • Sistema A: vulnerabilidades graves y muy graves
   • Sistema A: vulnerabilidades medias
   • Sistema A: vulnerabilidades leves
   • Sistema B: vulnerabilidades graves y muy graves
   • Sistema B: vulnerabilidades medias
   • Sistema B: vulnerabilidades leves
5. Conclusiones
6. Anexo A: Listado de vulnerabilidades detallado
7. Anexo B: Evidencias de los análisis realizados
   • Sistema A
   • Sistema B

Consejo 6: Crea un índice completo para tu documento. Haz que sea claro y limpio.

El resumen ejecutivo es tu mejor amigo

Este es el punto más importante de todo vuestro informe porque en algunos casos (por desgracia) es lo único que va a ser leído. Esto obliga a que el resumen ejecutivo sea posiblemente la parte del documento que tengáis que cuidar con más cariño.

Un buen resumen ejecutivo NUNCA tendría que ocupar más de una carilla de un A4 a letra normal (el mismo nombre lo dice, es un resumen para los jefes), y tendría que ser leído en menos de dos minutos.

Así mismo, un resumen ejecutivo tendría que tener un lenguaje extremadamente claro, huyendo siempre de terminología técnica (recuerda la audiencia, probablemente no serán técnicos). Aunque parezca algo drástico, yo siempre propongo la técnica del “niño de 6 años”: si vuestro informe no puede ser entendido sin problemas por un niño de 6 años, es que no es lo suficientemente claro.

¿Qué tendría que contener un buen resumen ejecutivo? Grosso modo, estos tres elementos:

1. Problema objeto del informe.
2. Solución propuesta.
3. Acciones tomadas (o que deben tomarse) para alcanzar esa solución.

Y nada más. El resumen ejecutivo debería de ser un ejercicio de minimalismo brutalista: si en lugar de una carilla podéis emplear media, mejor.

Consejo 7: Una carilla (o menos) en lenguaje claro identificando problema y soluciones tomadas constituyen un excelente resumen ejecutivo.

Los anexos son el trastero de tu informe

Uno de los errores más comunes cuando se realizan informes es la saturación de información. Nos hemos pegado una currada con el análisis del problema, y queremos que se note: listados de evidencias, capturas de pantalla, salidas de programas por comandos… todo tiene que estar reflejado en el informe para que se vea el trabajo que nos ha costado.

Error. Un listado sin fin de datos “porque sí” lo único que hace es producir fatiga cognitiva al lector, y dificulta en muchos casos la lectura del informe. Cuando tienes 600 páginas de informe, (y hemos visto algunos así), la simple navegación a lo largo del mismo es un infierno.

Estos elementos son muy interesantes a la hora de redactar un informe, ya que ayudan a defender nuestros análisis y conclusiones. Sin embargo, antes de incluirlos debes preguntarte: ¿son realmente necesarios? ¿Puedo usar un recorte del mismo?

La técnica del recorte (en la que se muestra únicamente parte de la evidencia recogida) es muy útil ya que nos permite centrarnos en lo importante. Por ejemplo, en una salida de una herramienta de port scanning de 5 páginas nos quedamos únicamente con las 4 líneas en las que aparece el puerto del servicio vulnerable.

El resto de la información tiene que estar incluida dentro del documento, principalmente por temas de verificabilidad del trabajo realizado, pero puede perfectamente ir como un anexo. De esta forma cualquiera que esté interesado puede ver la salida en bruto del comando, el subinforme completo de la herramienta X, etc… sin comprometer la legibilidad del texto.

Consejo 8: Todo lo que no sea realmente importante debe ir en los anexos del informe.

Haz de tu informe una plantilla

Antes de hacer un tipo de informe predeterminado, pregunta a quien tengas cerca si hay ya una plantilla hecha (es posible que ya exista, lo que te puede ahorrar mucho trabajo). En caso contrario, construye tu estructura, déjalo bonito… y convierte tu informe en una plantilla.

El motivo es claro: tal y como los programadores reusan código y los administradores de tareas automatizan tareas con scripts, tú también puedes reusar documentos. Un esfuerzo extra a la hora de hacer el primer documento tipo de un aspecto de tu trabajo para dejarlo perfecto hará que el resto de documentos sea “coger y rellenar plantilla”.

Consejo 9: Todo lo que no sea realmente importante debe ir en los anexos del informe.

Huye de los múltiples niveles anidados.

Hemos visto cosas que vosotros no creeríais. Atacar sangrías de texto en llamas más allá de Orion. Hemos visto estilos de texto infames brillar en la oscuridad, cerca de la puerta de Tannhäuser. Todos esos momentos se perderán en el tiempo como niveles 1.3.1.2.2.1.1 en tu informe técnico.

Bladerunner aparte, el consejo está claro: un informe que llega al 1.3.1.2.2.1.1 no es un informe, es tortura no tipificada por los DD.HH. Una estructura bizantina de subniveles, lo único que va a conseguir es confundir al lector y hacer que se pierda mientras intenta comprender tu documento.

En la mayoría de los casos la “regla del tres” funciona perfectamente: no más de 3 niveles de anidado en los títulos, ya que es un compromiso adecuado entre funcionalidad y legibilidad.

Consejo 10: Limita a 3 los subniveles de tu informe para no perder a tu audiencia.

[Advanced] – Convierte tu informe en un recortable

Si tu informe va a ser leído por personas con responsabilidades distintas (por ejemplo: sistemas, redes y seguridad) el estructurar tu informe para que sea fácilmente “recortable” puede facilitar muchísimo la vida a quien tenga que gestionar tu informe ya que puede darle a cada cual únicamente la parte del documento que le corresponde.

Por ejemplo, en una auditoria de seguridad en la que se auditan sistemas propios, sistemas alojados en un ISP y un combo de cortafuegos/WAF/IDS, puedes estructurar el informe de forma que sean tres “mini informes” y que simplemente cortando las páginas cada parte puede tener la información que necesita.

A veces es complicado, pero si lo consigues serás adorado por ello.

Consejo 11: Haz que tu informe sea fácilmente divisible.