Documentación técnica: ¿qué es, qué debería ser y quién la crea?
La preparación de la documentación del software es un paso muy importante en el proceso de desarrollo y lanzamiento del software. Lamentablemente, no todas las empresas le prestan la suficiente atención, lo que afecta negativamente tanto al mantenimiento y desarrollo del software, como a la interacción con sus usuarios.
Contenido:
1. ¿Qué es la documentación técnica del software? Sus tipos y formatos.
2. ¿Qué calidad debe tener la documentación?
3. ¿Qué son los términos de referencia y el diseño técnico?
4. ¿Quién es un redactor técnico? Características, tareas y problemas de esta profesión.
5. Resumiendo
En nuestro nuevo artículo, hablaremos sobre los beneficios de una documentación técnica competente. Aprenderá qué tipo de documentación se considera de alta calidad y qué debe incluir, qué tipos y formatos de dichos materiales existen y en qué se diferencian entre sí. Además, te hablaremos de la profesión de redactor técnico, qué debe saber hacer y cuál es la situación actual del mercado para estos especialistas.
¿Qué es la documentación técnica del software? Sus tipos y formatos.
La documentación del software es un conjunto de documentos que describen en detalle las características técnicas y las cualidades del consumidor del software, así como información sobre el proceso de su desarrollo, aplicación y mantenimiento.
El paquete de documentación del software incluye no solo materiales técnicos, sino también muchos otros tipos de documentos. Estos incluyen manuales, guías de usuario y ayuda, revisiones de software, especificaciones, procedimientos de prueba y más. Para facilitar la clasificación, toda esta documentación se divide en 4 categorías:
- Diseño (arquitectónico) . Describe los fundamentos, las metas, los objetivos y las etapas del proyecto que se utilizan para crear software y su entorno de trabajo. Es una descripción general del software, destinada principalmente a especialistas que trabajan en un proyecto.
- tecnico En ocasiones, absolutamente toda la documentación del software se denomina técnica, aunque esto no es del todo cierto. La documentación directamente técnica incluye una descripción del código del programa y las funciones que realiza, estructuras de datos, algoritmos, API e interfaces. Además, muestra en detalle el proceso de desarrollo de software, el principio de su funcionamiento y el procedimiento operativo. A menudo, estos materiales se suministran con el código fuente del programa o están integrados en él en forma de comentarios. Para simplificar la creación y actualización de documentos técnicos, utilizan plantillas especiales o lo hacen de forma automática mediante generadores de documentación (Javadoc, Doxygen, NDoc, etc.).
- personalizado Si los dos primeros tipos de materiales están enfocados a especialistas, entonces esta categoría está destinada a usuarios de software. No contiene descripciones técnicas complejas del código y cómo funciona; en cambio, se enfoca en describir las funciones del software y las reglas para su operación. Los formatos de documentación de usuario más comunes incluyen la Guía del usuario y la Referencia del usuario. También suele contener instrucciones para resolver problemas y respuestas a preguntas frecuentes.
- mercadeo Otro de los principales tipos de documentación de software son los materiales de marketing que ayudan a atraer la atención del público objetivo hacia el producto, informar sobre su propósito, capacidades y beneficios. A diferencia del marketing personalizado, la documentación de marketing es mucho más concisa. A menudo consiste en un solo folleto publicitario diseñado para familiarizar al usuario con un programa o aplicación.
¿Qué calidad debe tener la documentación?
En primer lugar, debe cumplir con un cierto conjunto de estándares. A saber, tales como:
- Estructuración . Tener una estructura clara es uno de los requisitos más importantes para la documentación técnica. Debe organizarse lógicamente en secciones y subsecciones, con párrafos, listas y otros elementos de formato de texto. Si estamos hablando de manuales de usuario, entonces solo una descripción de texto no es suficiente aquí, debe complementarse con capturas de pantalla del programa de alta calidad. No menos populares son los manuales en video que, sin embargo, no pueden reemplazar completamente los materiales de texto.
- uniformidad Toda la documentación del software debe estar en un solo formato, incluidos los documentos técnicos y de diseño para los empleados y los materiales para los usuarios. Además, en el curso de su redacción, debe verificar con otros documentos emitidos por su empresa para adherirse a un estilo corporativo uniforme. También será útil estandarizar previamente el proceso de elaboración de la documentación para evitar discrepancias en el futuro.
- Informatividad . Otro signo importante de la documentación de software de alta calidad es su claridad y contenido de información. Para lograr este objetivo, debe poder lograr un equilibrio entre la cantidad de datos y la simplicidad de su presentación. Tanto la falta de información como el exceso de información pueden empeorar este indicador, especialmente cuando se trata de la documentación del usuario. Por un lado, no es necesario hacerlo demasiado superficial y simplificado, y por otro lado, no se debe permitir una complicación excesiva del material.
- Relevancia Es imperativo que una buena documentación técnica esté dirigida a un público objetivo específico. Crear una guía común y única para desarrolladores y usuarios es una tarea interesante pero difícil que es poco probable que incluso un escritor técnico experimentado pueda lograr. Antes de desarrollar materiales, es recomendable determinar el círculo de empleados o clientes para quienes serán más útiles e interesantes. También es necesario tener una idea del nivel de preparación de la audiencia y cuáles son sus tareas y problemas que pueden ser resueltos por esta documentación.
¿Qué son los términos de referencia y el diseño técnico?
Por lo general, no es necesario escribir toda la documentación técnica antes del desarrollo del software. En la mayoría de los casos, los proyectos de TI modernos se crean de acuerdo con la metodología Agile y el trabajo en ellos se lleva a cabo en sprints, lo que le permite escribir documentación en paralelo con el proceso de desarrollo.
Sin embargo, existen varios documentos que idealmente deberían estar preparados antes del inicio del desarrollo del software: estos incluyen los términos de referencia (TOR) y el proyecto técnico (TP).
Los Términos de referencia son un documento preliminar clave, proporcionan una descripción general y el propósito del programa, sus objetivos comerciales, el alcance esperado del trabajo, así como el orden de las etapas de desarrollo, evaluación y aceptación del software. Los términos de referencia son elaborados por un analista comercial después de negociaciones con el cliente, por lo tanto, es necesario registrar con precisión y detalle todos sus requisitos y la visión del programa futuro. Si es necesario, también se discute con los miembros del equipo ejecutor del proyecto: desarrolladores, diseñadores, gerentes de proyecto, etc. De hecho, esta es una declaración del problema expresada en forma documental.
Después de redactar y acordar los términos de referencia, se comienza a trabajar en un proyecto técnico, que ya está siendo elaborado por un redactor técnico, no por un analista de negocios. TP es un conjunto de materiales que describe la arquitectura, escenarios, métodos, enfoques, soluciones técnicas y otros datos utilizados en el desarrollo del programa. Por ejemplo, en un proyecto técnico, muestran la estructura de servidores y bases de datos, diseños de interfaz, descripciones de algoritmos e integraciones con sistemas o equipos externos, scripts de usuario, etc.
En términos simples, si la tarea técnica responde a la pregunta "¿qué se debe hacer?", entonces el proyecto técnico, la pregunta "¿cómo hacerlo?"
¿Quién es un escritor de tecnología? Características, tareas y problemas de esta profesión.
El desarrollo de la documentación técnica para el software lo lleva a cabo un redactor técnico. Prepara casi todo tipo de materiales de este tipo, incluidos manuales y guías para usuarios, proyectos técnicos para especialistas, textos de marketing, etc. Las funciones de un redactor técnico incluyen:
- Registro de documentación técnica de acuerdo con normas internas (corporativas), estatales o internacionales.
- Hacer cambios y adiciones a la documentación a medida que se actualiza el software, manteniéndolo actualizado.
- Elaboración de materiales gráficos y multimedia (diagramas, gráficos, capturas de pantalla, videoguías) según los parámetros especificados y su inclusión en la documentación técnica.
- Testeo y análisis de nuevos programas y aplicaciones, aplicación de la experiencia y conocimientos adquiridos en la elaboración de documentación.
- Recopilación de la información necesaria sobre el software de todos los participantes del proyecto: desarrolladores, gerentes, diseñadores, evaluadores, clientes, etc.
- Traducción de documentación técnica a idiomas extranjeros, preparación de presentaciones técnicas, participación en procesos de implementación de software.
Idealmente, un escritor técnico profesional es un estudiante de humanidades con educación técnica que comprende los conceptos básicos del desarrollo de TI, posee terminología especializada, conoce algunos lenguajes de programación y marcado, así como herramientas de automatización para documentar procesos. Al mismo tiempo, debe tener ciertas habilidades filológicas para componer material técnico de manera concisa, informativa y comprensible tanto para especialistas como para usuarios comunes.
Sin embargo, tal versatilidad y multitarea está disponible para pocos, por lo que las empresas de TI a menudo se quejan de la dificultad de encontrar un buen redactor técnico. Por un lado, sus desarrolladores dirán lo mejor sobre el software, pero no saben cómo presentar el programa de manera sucinta y comprensible para un profano. Y los autores profesionales de textos, por regla general, no entienden la programación, por lo tanto, no pueden describir de manera precisa e informativa la estructura, las funciones y otros matices técnicos del software.
Resumiendo
La documentación del software incluye 4 tipos principales de materiales: diseño, técnico, personalizado y marketing. Puede elaborarse en paralelo con el desarrollo del software; de antemano, solo necesita preparar una tarea técnica y un proyecto técnico. La documentación de alta calidad debe necesariamente tener una estructura clara, estar redactada en un formato único, ser comprensible e informativa tanto para especialistas como para usuarios.
Además, la propiedad más importante de la documentación técnica es su conformidad con las solicitudes y necesidades del público objetivo. La documentación técnica está escrita por un especialista separado: un escritor técnico. No solo debe escribir y editar los textos relevantes, sino también preparar gráficos, videos y presentaciones, recopilar información sobre software, traducir documentación a idiomas extranjeros, probar y analizar programas y aplicaciones.
Apix-Drive es un conector de sistema simple y efectivo que lo ayudará a automatizar las tareas rutinarias y optimizar los procesos comerciales. Podrá ahorrar tiempo y dinero, dirigir estos recursos a objetivos más importantes. Probar ApiX-Drive y asegúrese de que esta herramienta descargue a sus empleados y después de 5 minutos de configuración, su negocio comenzará a funcionar más rápido.