Teoría sobre Optimización e documentación

Obxectivos

Máis ala de programar código... qué debe coñecer e facer un bo programador?

Debe saber cómo refactorizar o código utilizando patróns de deseño, usar sistemas de control de versións e realizar unha documentación útil e eficaz.

La documentación

Todo el proceso de desarrollo de software debe quedar perfectamente documentado, para pasar así de una fase a otra de forma clara y definida. Además, es importante también para poder acometer futuras revisiones del proyecto.

Las 7 C de la escritura técnica

Toda la documentación debería seguir estos principios:

• Clara: El objetivo es que la documentación sea sencilla de leer, de seguir y de comprender
• Concreta: Usar frases y palabras precisas con un único significado
• Concisa: Incluir toda la información que el usuario debe de conocer para ejecutar una acción concreta; no todo lo que idealmente puede saber.
• Cohesiva: Organizar el contenido de modo que siga un flujo lógico de información
• Consistente: Usar la misma terminología y estilo a lo largo de todo el documento
• Completa: Incluir toda la información necesaria para que el usuario ejecute de manera eficar procedimientos y acciones
• Coherente: Organizar el contenido de un modo que tenga sentdido y sea sencillo de entender

Errores comunes

Es interesante conocer cuáles son los errores más frecuentes para evitarlos. La documentación puede:

• Ser díficil de encontrar o estar en un lugar incorrecto
• No tener o tener demasiadas capturas de pantalla
• Tener demasiada narrativa o sólo videos
• Contener instrucciones que no están separadas por pasos
• Tener tíulos largos o poco descriptivos
• Estar desactualizada

Proceso de mejora de la usabilidad de la documentación

El mejor modo de saber si nuestra documentación es útil es midiendo su impacto. Para ello es necsario KPIs para medir la UX

Algunos posibles indicadores serían:

KPIs

Satisfacción de los usuarios	Usabilidad y ayuda	Calidad de la documentación
Net Promoter Score (NPS): tener más promotores que detractores	Encuestas e iconos de sentimientos	Feedback en soporte
Visitas al sitio: recurrentes vs nuevos	Keywords y técnicos más buscados	Net Promoter Score (NPS)
Inbound links: enlaces desde sitios externos	CTR, tasas recote, salidas	Casos de soporte resueltos

Un proceso de mejora que tenga en cuenta esos indicadores podría seguir estas fases:

1. Revisa los casos de soporte
2. Crea nueva documentación, mejora la existente y borra la desactualizada
3. Realiza test A/B
4. Mide resultados con los indicadoes

Tipos de guías

Se distinguen tres grandes documentos en el desarrollo de software:

Guía técnica

Información que contiene:

• El diseño de la aplicación.
• La codificación de los programas.
• Las pruebas realizadas.

Está dirigido a:

• Personal técnico en informática (analistas y programadores)

El objetivo es:

• Facilitar un correcto desarrollo, realizar correcciones en los programas y permitir un mantenimiento futuro.

Guía de uso

Información que contiene:

• Descripción de la funcionalidad de la aplicación.
• Forma de comenzar a ejecutar la aplicación.
• Ejemplos de uso del programa.
• Requerimientos software de la aplicación.
• Soluciones de los posibles problemas que se pueden presentar.

Está dirigido a:

• Usuarios que van a utilizar la aplicación (clientes).

El objetivo es:

• Dar a los usuarios finales toda la información necesaria para utilizar la aplicación.

Guía de instalación

Información que contiene:

• Toda la información necesaria sobre puesta en marcha, explotación y seguridad del sistema.

Está dirigido a:

• Personal informático responsable de la instalación, en colaboración con los usuarios que van a usar la aplicación (clientes).

El objetivo es :

• Dar toda la información necesaria para garantizar que la implantación de la aplicación se realice de forma segura, confiable y precisa.