La importancia de la documentacion tecnica
Para entender la importancia de la documentacion veamos un ejemplo.
Imaginemos que somos llamados para realizar nuestras practicas profesionales en la empresa Jcode. En dicha empresa necesitan una minima modificacion a el sistema encargado de las bases de datos de los empleados, ya que el encargado esta de vacaciones y las modificaciones son de prioridad maxima, si el practicante puede implementar dichas modificaciones aseguraria su puesto.
El requisito es el siguiente.
* No permitir que los nombres de los empleados en la base de datos contengan numeros; solo seran permitidios los caracteres.
* No permitir que los campos de nombres y apellidos queden vacios.
Inmediatamente te diriges a modificar el codigo fuente del sistema, y localizas la parte que ejecuta las inserciones a la base de datos.
public class insert {
String p;
String l;
String x;
EscuchaEventos m = new EscuchaEventos("as"1,true);
p = m.insen();
l = m.insea();
x = m.insee();
basedatos bd = new basedatos();
bd.upd(p,l,x);
}Al ver esto cualquiera se asustaria. Las variables no tienen mucho sentido, no hay forma de saber cuales son los elementos importantes, no tiene metodos implementados. No se sabe si esta clase es necesaria, y al parecer solo el encargado principal, aquel que escribio el codigo es capaz de interpretarlo.Quiza aun exista manera de arreglarlo, pero ahora imaginen que se quedan con el empleo.
Traten de visualizar todo el codigo igual de codificado, seria una pesadilla, no?
Es por ello que la documentacion tecnica es tan importante, a nivel de proyecto es indispensable mantener una documentacion limpia y clara para poder darle mantenimiento a nuestros propios sistemas o a sistemas ajenos.
Veamos este ejemplo de codigo.
public class Elevator {
public boolean doorOpen = false; // variable que indica si la puerta esta abierta
public int currentFloor = 1; // entro que indica el piso actual
public final int TOP_FLOOR = 4; // Constante donde se indica el maximo de pisos
public final int MIN_FLOOR = 0; // Constante donde se indica el minimo de pisos
// Metodo openDoor para abrir las puertas modificando la variable openDoor
public void openDoor() {
System.out.println("Abriendo puerta....");
doorOpen = true;
System.out.println("La puerta esta abierta.");
}
// Metodo closeDoor para cerrar las puertas modificando la variable openDoor
public void closeDoor() {
System.out.println("Cerrando puerta ....");
doorOpen = false;
System.out.println("La puerta esta cerrada.");
}
// Metodo goUp para aumentar el currentFloor y desplegar en pantalla el piso actual
public void goUp() {
System.out.println("Subiendo un piso.");
currentFloor++;
System.out.println("Estamos en el piso: " + currentFloor);
}
// Metodo goDown para decrementar el currentFloor y desplegar en pantalla el piso acutal
public void goDown() {
System.out.println("Bajando un piso.");
currentFloor--;
System.out.println("Estamos en el piso: " + currentFloor);
}
} Al ver un codigo asi es mas facil comprender y modificar su estructura, es un hecho. Como un consejo extra, la documentacion tecnica esta bien acompañada de un estandar de codigo esto hace una lectura y comprension tan sencilla que es facil aplicarles mantenimiento a los sistemas ademas de aplicarles optimizaciones. 
