Documentación técnica en el idioma de Cervantes

Los documentos técnicos cumplen el propósito de informar de lo que se ha hecho en una actividad determinada en términos técnicos y de forma que sea legible y comprensible dentro de su contexto. En la documentación técnica existen unos criterios determinados para su elaboración. En este articulo intentaremos mencionar los principales a tener en cuenta.


Lenguaje

Un documento técnico se escribe en lenguaje técnico. El lenguaje técnico evita la utilización de palabras con significados ambiguos. El lenguaje técnico es preciso en los significados, abunda en la aplicación de los términos técnicos propios del dominio sobre el que se habla, y estructura el contenido a base de frases cortas y directas. Esto último significa que el lenguaje técnico no utiliza recursos como tropos, metáforas ni otros elementos propios del lenguaje literario.

El documento técnico debe mantener la corrección técnica del contenido y de la estructura con respecto a los objetivos y naturaleza del proyecto. La utilización de términos fuera del dominio técnico, de metodologías o técnicas no contrastadas, de resultados incoherentes, de afirmaciones o conclusiones no fundamentadas, etc., es síntoma inequívoco de incorrección técnica.

Gramática

Las frases deben aplicar construcciones gramaticales regulares: en primer lugar, el sintagma nominal (sujeto y complementos). En segundo lugar, el sintagma verbal (verbo y complementos). También se suelen utilizar frases relativas que extienden el significado (-frase principal- que -frase relativa-).

Sujeto

El lenguaje técnico utiliza el sujeto impersonal o reflexivo, tal y como se está aplicando en el presente documento:

    "se puede ver"
    "se describe"

A veces, también se usa la primera persona del plural cuando el autor pretende implicarse con el lector en una actividad determinada que se está realizando en el momento presente

    "vamos a poner el dispositivo en marcha"
    "veamos el resultado"

Debemos huir de la aplicación de la primera persona del singular

    "yo incluyo el informe"
    "yo conecto el módulo"

Cuando se quiere enfatizar o recalcar información relativa al autor, se puede utilizar términos estereotipados como

    "el autor"
    "el que suscribe"

Y cuando se quiere mencionar la participación activa del lector, usaremos

    "el usuario"
    "el lector"

Tiempos verbales

Hay que ser cuidadoso en el uso de los tiempos verbales de las frases y párrafos. No es correcto mezclar pretéritos, presentes y futuros en un mismo documento o sección del documento. En un documento o parte del mismo donde se describe una actividad o un conjunto de actividades ya realizadas y concluidas, se suele aplicar el pretérito perfecto:

    "se ha procedido al cálculo del promedio"
    "se han establecido los requisitos fundamentales"

A veces, también se puede combinar con el pretérito imperfecto cuando se refiere a acciones puntuales

    "el programa dio un error"
    "saltó la alarma en el momento en que"

Cuando se describe un procedimiento a realizar, normalmente se utiliza el presente de indicativo

    "se abre el menú de edición"
    "se selecciona la opción"

Cuando se describe el contenido que se incluye a continuación en una sección, subsección o apartado del documento, se puede utilizar el futuro imperfecto así,

    "se mostrará el resultado del proyecto"
    "se va a mostrar el resultado del proyecto"

Finalmente, para indicar acciones que el lector debe realizar, se aplica el imperativo

    "véase la Figura"

o las siguientes construcciones

    "hay que"
    "se debe"

Narración

La narración o descripción debe ser fluida y fácil de leer, cuidando especialmente la corrección ortográfica y terminológica. Deben evitarse las frases rebuscadas, el uso del lenguaje coloquial, o la inserción no justificada de citas, tablas, figuras, etc. que no aporten nada al texto. El texto debe componerse a base de frases cortas separadas por puntos y seguidos. Su extensión debe adecuarse a los objetivos establecidos al comienzo del documento. Todos los elementos técnicos que deban ser citados o presentados exhaustivamente se deben poner en anexos al cuerpo del documento. Incluso se puede incluir una relación de abreviaturas, términos comunes o un glosario de términos técnicos para evitar confusiones semánticas.

Inserciones de figuras y tablas

Debe adecuarse la cantidad de tablas y figuras al contenido del documento, evitando incluir demasiadas tablas y figuras que no aporten casi nada al texto. Es mejor alternar descripciones textuales con tablas y figuras. Salvo necesidades concretas, no es necesario explicar profusamente una figura o una tabla con texto suplementario.

La inserción de referencias a figuras y tablas puede hacerse de dos formas distintas: conexa e inconexa. La forma de inserción inconexa consiste en utilizar la construcción

    "(Véase la Figura 27)"

como una frase independiente entre paréntesis. La forma de inserción conexa consiste en utilizar un párrafo introductorio que establece una relación con el contenido y/o descripción de la figura o tabla:

    "En la Figura 27 se puede apreciar que...",
    "existe un indicador, tal como se muestra en la Figura 27..."

Por otra parte, los términos "Figura" y "Tabla" deben aparecer en el texto con la inicial en mayúscula.

Bibliografía y referencias

En muchos documentos técnicos habitualmente se incluye información que proviene de otro u otros documentos distintos. Es costumbre y por supuesto, ético, citar las fuentes externas que proporcionan dicha información.

Internet provee de algunas herramientas como esta que permiten descubrir si el contenido de un documento ha sido plagiado. Por tanto, debemos referenciar a nuestras fuentes para evitar incurrir en el delito de plagio.

Respecto a la bibliografía, en un documento técnico hay que distinguir por un lado la inserción de las referencias a las fuentes, y por otro lado, la relación detallada de dichas fuentes.

Inserción de las referencias a las fuentes

La inserción de referencias a una fuente de información externa, sea libro, articulo de investigación u otro tipo de obra, se hace mediante paréntesis siguiendo estas normas:

Cuando la referencia tiene un solo autor, se incluye el primer apellido de éste y el año de publicación con todas las cifras:

    (Tanembaum, 2001)

Cuando la referencia tiene más de un autor, la estructura es la misma salvo que, en lugar de poner todos los apellidos, se añade al apellido del primer autor la terminación "et al.":

    (Harmelen et al., 2004)

Relación de referencias

La relación de referencias se hace en un capitulo o sección independiente del documento. Se recopilan todos los datos relativos a cada una de las fuentes, ordenadas alfabéticamente de menor a mayor por el apellido del primer autor.

El formato con el que deben citarse las referencias bibliográficas depende de si la fuente es un libro, un capitulo de un libro, un articulo de revista, una obra no publicada, una dirección web, etc.. Se muestran algunos ejemplos a nivel orientativo:

Referencia a un libro:

    [Alonso, 2009]: Alonso J.A. Redes privadas virtuales. 1ª ed. Ra-ma,
    Madrid, 2009.

Referencia a un artículo de investigación:

    [Siebes, 2005]: Siebes R. pNear: combining content clustering and
    distributed hash tables. Vrije Universiteit Amsterdam. The netherland,
    2005.

Referencia a una URL:

    [Castell, 2010]: Castell A.I. Documentación
    técnica en el idioma de Cervantes.
    http://aicastell.blogspot.com/2010/09/documentacion-tecnica-en-el-idioma-de.html.
    Acceso el 25/09/2010.

Estructura del documento

El documento se divide en secciones, subsecciones y apartados. Salvo en contadas excepciones, no se recomienda llegar a un mayor nivel de división. En todos ellos, la unidad de redacción y de estilo es el párrafo, compuesto por un conjunto de frases. Al párrafo se le aplican una serie de características de formato y aspecto como son la separación de párrafos, interlineado, justificación entre margenes, tipo y tamaño de letra, etc.

De forma muy genérica, podemos organizar la estructura de un documento técnico con los siguientes apartados:

    Portada
    Información visible sobre el titulo del documento y nombre del autor.

    Resumen
    Objetivos, descripción, resultados y conclusiones del trabajo resumidos
    en no mas de 500 y no menos de 300 palabras.

    Palabras clave
    5 términos alusivos al contenido y propósitos del documento para poder
    aplicar una indexación del mismo.

    Indice
    Relación de secciones y subsecciones, sin llegar a los apartados.

    Introducción
    Objetivos del documento, descripción del contexto general, planteamiento
    del problema, descripción resumida del contenido del resto del documento.

    Descripción
    Descripción detallada de todo el trabajo realizado.

    Resultados
    Descripción de los resultados obtenidos en el trabajo realizado.

    Conclusiones
    Redacción de las conclusiones obtenidas, interpretación de los
    resultados, de las afirmaciones fundamentadas y de las posibles
    ampliaciones en sucesivos trabajos.

    Bibliografía
    Relación de referencias utilizadas durante la redacción del documento

    Anexos
    Inclusión de anexos con información complementaria sobre la que se
    aporta en el cuerpo del documento. Esta sección es opcional.

    Indice de tablas
    Relación de las tablas contenidas en el documento.

    Indice de figuras
    Relación de las figuras contenidas en el documento.

    Terminología
    Relación de términos y abreviaciones utilizados en el documento con una
    breve explicación de su significado para evitar confusiones al lector.

Herramientas

Por último, en la elaboración de toda la documentación se debe contar por supuesto con el apoyo de herramientas informáticas del estilo de Open Office o LaTeX. La persona encargada de llevar a cabo la documentación técnica debe tener los conocimientos suficientes de estos programas para obtener el debido provecho.