.. include-document:: reference-links
   :rest:


El proceso de redactar documentación, debe abordarse como 
un proceso de desarrollo más, no es bastante con sentarse 
y comenzar a escribir “a ver que sale”. Como todo proceso 
de desarrollo debe comenzar por una fase de análisis, 
para a continuación redactar, y finalmente debe existir 
una fase de revisión del texto que se ha creado.

Este proceso debe abordarse desde las siguientes premisas 
fundamentales:

a.  El autor debe tener en todo momento presente qué y para 
    quién escribe. El destinatario del texto es el usuario.

b.  El autor no debe tener ningún protagonismo en la obra 
    en el sentido de que se escribe por y para un tema, no 
    por una recreación artística.

c.  El objetivo primordial del texto es que el lector comprenda 
    la herramienta y cómo usarla.


Fases en la confección de la documentación
---------------------------------------------

A la hora de ponernos a confeccionar la documentación contemplaremos 
tres fases o momentos a tener en cuenta:

* La *planificación*

* La *redacción*.

* La *revisión*.

Planificación
...............

El objetivo de esta fase es estructurar las ideas y marcar las directrices del trabajo que se piensa acometer, el redactor debe generar un esquema con esa estructura de ideas de forma jerarquizada. Este esquema proporciona una primera visión del conjunto del trabajo.

Una vez que se han plasmado las ideas generales en el esquema jerarquizado lo siguiente que debe hacerse es completar el esquema con las divisiones y subdivisiones de las entradas generales que permitan exponer claramente las ideas del redactor y desarrollar el tema principal. Este esquema no se debe presuponer inmutable, es decir, podemos añadir “voces” al esquema que sirvan para completarlo, o suprimir “voces” porque nos damos cuenta que no vienen al caso, o simplemente modificarlo porque no nos convence el enunciado propuesto.


Redacción
............

En esta etapa se transforma en texto el esquema que se creó en la fase de planificación. Se debe tener en cuenta el léxico, el orden sintáctico, la concordancia, la cohesión, la puntuación y todos los elementos que aseguren un estilo claro, preciso, conciso y sencillo.

Comunicarse con precisión y claridad significa que el texto se lee y se entiende rápidamente. Un texto es fácil de entender cuando el lenguaje es sencillo, las oraciones están bien construidas y cada párrafo desarrolla su tema siguiendo un orden lógico.

Las oraciones que se utilicen deben ser simples. Las oraciones largas son generalmente más difíciles de entender que las oraciones cortas, porque mientras más larga es la oración mayor es la probabilidad de que el sujeto y el verbo se aparten, o que la oración contenga tanta información que el lector olvide el material importante. No obstante, hay oraciones cortas tan mal construidas que son imposibles de entender y hay oraciones muy largas pero tan bien organizadas y puntuadas que se entienden perfectamente.

Es conveniente alternar párrafos largos con otros más cortos. No se deben utilizar exclusivamente párrafos y oraciones cortas. Una secuencia de varios párrafos cortos, al igual que una secuencia de oraciones cortas, contiene demasiadas pausas y no proporciona una lectura agradable. En el otro extremo, un párrafo que ocupa la página completa es abrumador y no invita a la lectura.

Se debe incluir sólo información pertinente al contenido y comunicar dicha información usando el menor número posible de palabras, el texto innecesario desvía la atención del lector y afecta la claridad del mensaje.

Hay que usar palabras comunes en vez de términos rebuscados, usar aquellas palabras que comuniquen exactamente lo que se quiere transmitir. Si el lector no entiende algo, no puede levantar la mano para aclarar sus dudas, ni puede adivinar cuál era la intención del redactor cuando escribió el texto; para escribir con precisión se tiene que escribir para el lector.

Si se trabaja con prisa y no se revisa cuidadosamente el orden de las palabras, seguramente se escribirán muchas oraciones deficientes. El significado literal de la oración puede ser tan absurdo que el lector sonreirá pero entenderá el mensaje. En otras ocasiones el significado será confuso y el lector deberá retroceder y leer la oración varias veces para intentar entenderla. El significado también puede ser opuesto o totalmente distinto de lo que quieres comunicar


Revisión
.............

Con la revisión lo que se pretende es corregir aquellos errores que se hayan podido cometer asegurando la corrección, la adecuación, la concisión, la precisión, la coherencia, la claridad y la legibilidad del texto. Se examinan tanto las ideas como las oraciones, los párrafos, los apartes y/o los capítulos que se han redactado.

La revisión se hace en dos pasos:

* **Primero**: el redactor comprueba que el texto responde a su 
  intención comunicativa y que ha logrado la expresión correcta de 
  lo que ha planeado comunicar a sus lectores potenciales.

* **Segundo**: modifica la parte o las partes formales del texto 
  que sea necesario, esto es el léxico, la morfología, la sintaxis, 
  la ortografía, la puntuación, el diseño, etc.

Para llevar a cabo una revisión efectiva del texto, que detecte los problemas tanto formales como de fondo, es conveniente hacerlo de dos maneras: como redactor y como lector.


Abreviaturas
--------------

Las abreviaturas son convenientes porque ahorran espacio y aligeran 
la lectura, pero pueden confundir al lector si sus significados 
no están claros. Las normas siguientes ayudan a usar las 
abreviaturas correctamente:

1.  No deben usarse abreviaturas en el título ni en el resumen.

2.  No se deben abreviar términos cortos.

3.  No se deben abreviar términos que se usan pocas veces.

4.  No inventes abreviaturas

5.  No comiences las oraciones con abreviaturas. 
    Tampoco comiences las oraciones con números.

6.  Para definir una abreviatura se escribe el término completo 
    la primera vez que se usa y a continuación la abreviatura 
    entre paréntesis.

7.  Abrevia las unidades de medida cuando están precedidas de 
    dígitos, pero no cuando son sustantivos.

8.  Representa los números con dígitos cuando se refieren a unidades 
    de medida (4 gr., 18 m.) y cuando se usan para expresar horas y 
    fechas. Representa los números con palabras cuando se usan como 
    sustantivos (nosotros cuatro). 
    Usa las abreviaturas del Sistema Internacional (SI) para todas 
    las unidades de medida.


Documentación adicional
--------------------------

* *El proceso lógico en la redacción*, http://www.arrakis.es/~serprof/redac.html

* *Manual de Redacción Científica*, http://www.emagister.com/manual-redaccion-cientifica-cursos-312647.htm

* *Textos científicos, humanísticos y técnicos*, http://www.auladeletras.net, http://www.auladeletras.net/material/ciencia.PDF