Virfia PRN115 U1 CT 1.2-1.2 Me

UNIVERSIDAD DE EL SALVADOR EN LÍNEA
FACULTAD DE INGENIERÍA Y ARQUITECTURA

PROGRAMACION I
TÉCNICAS DE DOCUMENTACIÓN
1. INTRODUCCIÓN
La mayoría de algoritmos diseñados e implementados son utilizados por otras personas y no
por quien los escribió. Por ejemplo, quien diseñó el programa para calcular el salario a los
empleados de una empresa, generalmente no es quien imprime las planillas; el que diseña el
programa para facturarle a un cliente de un almacén no es el que realiza la factura; en
resumen, el ingeniero que construye la solución de un determinado problema no será la
misma persona que la utilizará.
De la misma manera habrán personas que luego tomaran esas soluciones y deberán agregar
otras funcionalidades, por lo cual deberán tener a la mano toda una documentación para
conocer de manera práctica, el funcionamiento de la misma y la forma en como realiza esa
solución.
Por esta razón, los algoritmos y programas deben ser fáciles de utilizar, debido a que la
mayoría de las veces quien utiliza el programa no tiene nociones de programación; por otra
parte, quien les da mantenimiento puede ser un programador diferente al que los construyó.
Las siguientes situaciones ilustran la necesidad de escribir programas fáciles de utilizar:
 El usuario tiene que saber, qué tipo de datos introducir, en qué momento hacerlo y
cuántos datos introducir.
 En el caso de las salidas de datos, el usuario o quien lee estos reportes, debe saber
qué
representa esa información.
 Además, para darle el mantenimiento necesario a la solución construida se necesita
saber qué hace y cómo lo hace.
En conclusión, se debe recordar que las soluciones deben ser lo más claras (documentar) y
explícitas posibles, para que otra persona, trabaje, modifique o califique el trabajo realizado.
2. OBJETIVO DE LA UNIDAD
Aplicar las Técnicas de Documentación en el desarrollo de software.
Este material ha sido proporcionado al estudiante en el marco de su formación a través de una carrera en línea en la
Universidad de El Salvador. Se han respetado los derechos de autor para su elaboración. El debido uso del mismo es
responsabilidad del estudiante
PROGRAMACION I
3. IMPORTANCIA DE LA DOCUMENTACIÓN
Documento proviene del latín documentu, que significa enseñar. Se refiere a un escrito con el
que se prueba, acredita o hace constar alguna cosa. El documento es definido como el escrito
susceptible de poder contribuir como prueba a los hechos en un proceso determinado. En el
sentido extenso del vocablo, es un acto humano perceptible que puede servir de prueba para
determinados hechos de un proceso. Todo conocimiento fijado materialmente sobre un soporte,
y susceptible de ser utilizado para consulta, estudio o trabajo. Un utensilio irreemplazable para
transmitir los conocimientos, las ideas y dar cuenta de los hechos.
Son funciones de un documento:
 Permitir la comunicación humana.

 Servir de medio valioso de formación y enseñanza.
 Materializar todos los conocimientos humanos formando una memoria colectiva.
Un documento válido debe ser:
Original: de primera mano, fruto de un estudio o investigación.

Fiable: digno de crédito. Identificación de autores y fuentes.
Utilizable: con posibilidad de difusión. De fácil acceso a los usuarios.
Documentos confidenciales: de utilidad limitada.
La Documentación es la parte de la Programación que se encarga de escribir la “literatura”

necesaria para comprender perfectamente una solución. Consiste en escribir detalladamente
todo lo que se necesita conocer para trabajar con ella y modificarla por mantenimiento, cuando
sea requerido. Es una guía o comunicación escrita en variadas formas: enunciados,
procedimientos, dibujos o diagramas. En términos generales, la Documentación es el acto de
reunir documentos sobre un tema dado y el tratamiento de éstos en vistas a su difusión. Debe
poseer las siguientes características:
Pertinencia: los documentos que se proporcionan deben responder a las necesidades específicas
de los usuarios.
Exhaustividad: debe proporcionarse al usuario todos los documentos que respondan a sus
necesidades.
Rapidez: los documentos pertinentes deben transmitirse al usuario interesado inmediatamente

después de su publicación.
PROGRAMACION I
Economía: el costo de la Documentación debe ser mínimo.
A continuación, se escriben algunas preguntas básicas orientadoras para la redacción de la

documentación:
a) Salida de Datos:
a. ¿Qué hace el algoritmo o programa?
b. ¿Se divide el programa en partes o módulos?
c. ¿Cuántos módulos son?
d. ¿Qué hace o genera cada uno de los módulos?
b) Entrada de Datos:
a. ¿Qué tipo de datos necesita?
b. ¿Cuántos?
c) Información de Hardware y Software:
a. ¿Qué necesita para funcionar?
d) Procesamiento de Datos:
a. ¿Cómo lo hace?
e) Información General:
a. ¿Quién lo hizo?
b. ¿Cuándo lo hizo?
c. ¿Para quién fue desarrollado?
d. ¿Cuándo, por quién y qué se le ha modificado?
Como ya se expuso anteriormente, los programas o algoritmos son diseñados muchas veces para
que otras personas, usuarios, los utilicen; por ejemplo, los algoritmos que los estudiantes
diseñan, los utilizan los profesores para revisarlos y calificarlos. La mayoría de veces los usuarios
no tienen los conocimientos necesarios (matemáticos o de programación) lo que dificulta la
utilización de la solución, es aquí donde radica la importancia y aplicación de la Documentación.
El programador debe indicar al usuario cómo trabajar con la solución, proponiéndole mensajes
con las indicaciones siguientes:
¿Cuándo introducir datos?
¿Qué tipo de datos?
¿Cuántos datos necesita introducir?
PROGRAMACION I
Un aspecto que hace que las aplicaciones sean amigables, cuando el proceso que realiza el
programa toma un tiempo considerable (más de un minuto), el programador debe indicarle al
usuario, por medio de mensajes que el programa está trabajando y que presentará en los
siguientes minutos los resultados esperados.
El mantenimiento de un programa, también se facilita mediante la Documentación, ya que,

generalmente esta tarea le corresponde realizarla a alguien que no diseñó el programa. Gracias
a la Documentación se puede saber qué variables se utilizan, qué estructuras lógicas de control
se han utilizado y así modificar la lógica del programa para que éste siga funcionando y produzca
la información requerida y correcta.
Los programas de aplicación necesitan de cierto hardware y software para instalarlos y que se
puedan utilizar. Estos requerimientos de equipo (capacidad de memoria RAM, espacio a utilizar
en disco, tipo de impresor configurado, dispositivos manejables, etc.) y software (sistema
operativo, plataforma de desarrollo, compilador, traductor o intérprete, llamadas a rutinas
escritas en otros lenguajes de programación, etc.) también son detalladas en la Documentación
del programa.
4. ESTANDARIZACIÓN Y NORMALIZACIÓN
El uso de procedimientos y documentación estandarizada proporciona la base de una
comunicación clara y rápida, adiestramiento menos costoso del personal de sistemas, reducción
de costos de almacenamiento, y otros.
Estandarización significa el uso de símbolos convencionales en los diagramas que describen el

sistema y el uso de un formato uniforme en todos los documentos que se generen.
4.1. VENTAJAS DE LA ESTANDARIZACIÓN

- Ayuda al entrenamiento de nuevo personal en el sistema documentado.
- Sirve de referencia para los usuarios que mantienen y auditan el sistema.
- Ayuda a los analistas y diseñadores de sistemas trabajo de integración de sistemas.
- Asegura que el sistema opere correctamente.
Estándares Básicos
Toda documentación que se relacione con un sistema, ya sea manual o por computadora,
sencillo o complejo debe reunir los siguientes requisitos básicos:
PROGRAMACION I
- Debe ser rotulada con claridad y bien organizada, con secciones claramente indicadas,
almacenarlas en carpetas e índice.
- Los diagramas deberán ser claros, no aglomerados y la escritura manuscrita deberá ser
legible.
- La documentación deberá ser completa.
- Se incluirá una leyenda o explicación de los términos utilizados.
- La documentación siempre se debe conserva actualizada.
4.2. NORMALIZACIÓN
Las normas son las especificaciones sobre la forma en que se debe realizar la documentación, en
ella se define el esquema que deben llevar desde las etiquetas en el código fuente, hasta las
secciones, formato de citas al pie, bibliografía citada y hasta el esquema de carpetas que deben
seguirse para almacenar los documentos o manuales entregados por el equipo de diseño y
desarrollo del sistema.
Tipos de Documentación
Dependiendo del tipo de documentación, para Sistemas Informáticos existen dos tipos de
documentación.
 Documentación Interna
La documentación interna está formada por los comentarios que los programadores escriben
dentro del código fuente durante la fase de desarrollo.
El desafío de la documentación interna es garantizar que se mantienen y actualizan los

comentarios al mismo tiempo que lo hace el código fuente.
 Documentación Externa
La documentación externa son todos los documentos que se han ido generando en todas las
etapas anteriores en el desarrollo de un sistema y que se administran fuera del código fuente del
sistema, como por ejemplo el manual administrativo, los archivos de ayuda, manuales de usuario,
y los documentos de diseño y especificaciones.
PROGRAMACION I
5. DOCUMENTACIÓN INTERNA
5.1. DEFINICIÓN
Es la Documentación de Código Fuente, se encuentra escrita dentro del programa en forma de
mensajes, puede ser en forma de comentarios o de archivos de información dentro de la
aplicación. Es necesario comentar convenientemente cada una de las partes que tiene el
programa. Estos comentarios se incluyen en el código fuente con el objeto de clarificar y explicar
cada elemento del programa, se deben de comentar las variables, los módulos y en definitiva
todo elemento que se considere importante.
Esta documentación tiene como objeto hacer más comprensible el código fuente a otros
programadores que tengan que trabajar con él, ya sea porque forman parte del grupo de
desarrollo o porque el programa va a ser mantenido o modificado por otra persona distinta al
programador inicial.
También resulta muy útil durante la depuración y el mantenimiento del programa por el propio
programador, al paso del tiempo las decisiones se olvidan y surgen dudas hasta en el propio
programador de porqué se hicieron las cosas de una determinada manera y no de otra. Se pueden
incluir comentarios como:
● Nombre del programador
● Fecha en que se diseñó el programa
● Tipo de datos que necesita el programa en el momento de su ejecución
● Aclaración o ampliación de los datos de salida cuando sean mostrados al usuario, ya sea en
el monitor o en el impresor
● Descripción de lo que hace una parte o módulo del programa
En suma, la Documentación es el conjunto de información que describe qué hacen los sistemas
informáticos, cómo lo hacen y para quién lo hacen. Consiste en material que explica las características
técnicas y la operación de un sistema. Es esencial para proporcionar entendimiento de un sistema a
quien lo vaya a usar para mantenerlo, para permitir auditoría del sistema y para enseñar a los usuarios
cómo interactuar con el sistema y hacerlo funcionar.
Es una buena técnica de escritura de código fuente, adoptar el Estilo Camel1
El Estilo Camel es un modo de escritura que se aplica a identificadores compuestos por varias
palabras. El nombre “camel” se debe a que las mayúsculas a lo largo de una palabra en este estilo
se asemejan a las jorobas de un camello, se podría traducir como Mayúsculas/Minúsculas en
Estilo Camello. Existen dos tipos:
1 Microsoft. (2003 de 01 de 01). Microsoft Developer Network. Obtenido del siguiente enlace
PROGRAMACION I
● UpperCamel: cuando la primera letra de cada una de las palabras es mayúscula.

Ejemplo: EjemploDeUpperCamel.
● lowerCamel: igual que la anterior con la excepción de que la primera letra es minúscula.
Ejemplo: ejemploDeLowerCamelCase.
5.2. CONVENCIONES BÁSICAS PARA LA DOCUMENTACIÓN

Recomendaciones para una correcta documentación:
● Antes de la implementación, quite todos los comentarios temporales o innecesarios, para

evitar cualquier confusión en la futura fase de mantenimiento.
● Si necesita realizar comentarios para explicar una sección de código compleja, examine el
código para decidir si debería volver a escribirlo. No documente un código que no
funciona, re escríbalo. Es indispensable un equilibrio entre rendimiento y mantenibilidad.
● Use frases completas cuando escriba comentarios. Los comentarios deben aclarar el
código, no añadirle ambigüedad.
● Vaya comentando al mismo tiempo que programa, porque probablemente no tenga
tiempo de hacerlo más tarde. Lo que parece obvio hoy es posible que mañana no lo sea.
● Evite comentarios superfluos o inapropiados.
● Use los comentarios para explicar el propósito del código. No los use como si fueran
traducciones interlineales.
● Comente cualquier cosa que no sea legible de forma obvia en el código.
● Para evitar problemas recurrentes, haga siempre comentarios al depurar errores y
solucionar problemas de codificación, especialmente cuando trabaje en equipo.
● Haga comentarios en el código que esté formado por bucles o bifurcaciones lógicas. Se
trata en estos casos de áreas clave que ayudarán a los lectores del código fuente.
● Realice los comentarios en un estilo uniforme, respetando una puntuación y estructura
coherentes a lo largo de toda la aplicación.
● Separe los comentarios de sus delimitadores mediante espacios. Si respeta estas normas,
los comentarios serán más claros y fáciles de localizar si trabaja sin indicaciones de color.
PROGRAMACION I
5.3. COMENTARIOS BÁSICOS

En C# puedes escribir comentarios de una línea empezando por "//" o de varias líneas escribiendo
entre "/*" y "*/".
//comentario de una línea
int x = 1; //valor de a
/* comentario
* de varias
* líneas */
int y = x;
5.4. ETIQUETAS XML

A continuación, se presenta una tabla con las etiquetas recomendadas para la documentación,
de igual manera se indica en donde pueden ser utilizadas:
Etiqueta Clase Estructur Interfac Enumeració Delegad Constant Propieda Métod
a e n o e d o
<summary X X X X X X X X
>
<remarks> X X X X X X X X
<para> X X X X X X X X
<list> X X X X X X X X
<example> X X X X X X X X
<code> X X X X X X X X
<param> X X
<paramref X X
>
<return> X
<see> X X X X X X X X
<seealso> X X X X X X X X
<exception X X
>
<value> X X
PROGRAMACION I
Documentación de Clases
Para documentar una clase normalmente se utilizan las siguientes etiquetas:
Etiqueta <summary>
Sintaxis: <summary>description</summary>
Descripción:
Proporciona una descripción del tipo del miembro que estamos documentando, procure ser lo
más específico posible para que se entienda de manera sencilla el propósito que se logra obtener.
El IDE de Visual Studio tiene una función llamada Edición de comentarios automática, que inserta
automáticamente las etiquetas <summary> y </summary> y sitúa el cursor entre ambas después
de que haya escrito el delimitador ///.
El texto para la etiqueta <summary> es la única fuente de información sobre el tipo en IntelliSense,
y también se muestra en el explorador de objetos y en el Informe Web de comentario de código
Etiqueta <remarks>
Sintaxis: <remarks>description</remarks>
Descripción:
Normalmente es utilizado en conjunto con la etiqueta <summary>, y su objetivo es proporcionar
documentación a manera de información complementaria con lo cual ayuda a ser un poco más
específico en cuanto a consideraciones que deben de tomarse en cuenta.
Esta información se muestra en el Examinador de objetos y en el Informe Web de comentario de

código.
Ejemplo:
/// <summary>
/// Clase principal de la aplicación.
/// </summary>
/// <remarks>
/// Recuerde que los parámetros de esta clase no son opcionales...
/// </remarks>
class MiApp {
static void Main(string[] args) {
...
}
}
PROGRAMACION I
Documentación de Métodos / Funciones

Etiqueta <returns>
Sintaxis: <returns>description</returns>
Descripción:
Específica el valor de retorno de una función. La etiqueta <returns> se debe utilizar en el

comentario de una declaración de método para describir el valor devuelto por el método.
Etiqueta <param>
Sintaxis: <param name='name'>description</param>
Descripción:
Esta etiqueta describe los parámetros que requiere una determinada función, Para utilizar esta
etiqueta es necesario especificar sus atributos name el cual especifica el nombre del parámetro
y description mediante el cual proporcionamos la descripción del parámetro.
La etiqueta <param> se usa para describir parámetros. Cuando se utiliza, el compilador

comprueba si el parámetro existe y si todos los parámetros están descritos en la documentación.
Si la comprobación no tiene éxito, el compilador emite una advertencia. El texto para la etiqueta
<param> se mostrará en IntelliSense, el Examinador de objetos y en el Informe Web de
comentario de código.
Ejemplo:
/// <summary>
/// Retorna el valor de un booleano contrario al valor parametrizado.
/// </summary>
/// <return>
/// Devuelve true o false dependiendo del valor parametrizado.
/// </return>
/// <param name="valor">
/// valor booleano a evaluar.
/// </param>
public bool EvaluarValor(bool valor) {
bool x = valor;
...
return !x;
}
PROGRAMACION I
Etiquetas especiales
Etiqueta <example>
Sintaxis: <example>description</example>
Descripción:
La etiqueta <example> permite especificar un ejemplo de cómo utilizar un método u otro

miembro de una biblioteca. Normalmente, esto implicaría el uso de la etiqueta <code>.
Ejemplo:
/// <summary>
/// El método ObtenerCero.
/// </summary>
/// <example>
/// Este ejemplo muestra cómo llamar al método <see cref="ObtenerCero"/>.
/// <code>
/// class ClasePrueba
/// {
/// static int Main()
/// {
/// return ObtenerCero();
/// }
/// }
/// </code>
/// </example>
public static int ObtenerCero()
{
return 0;
}
Etiqueta <code>
Sintaxis: <code>content</code>
Descripción:
La etiqueta <code> proporciona un modo de marcar varias líneas como código. Todo lo que está
contenido dentro de la etiqueta <code></code> es considerado como texto en forma de código
y normalmente se utiliza dentro de una etiqueta <example>
PROGRAMACION I
Ejemplo: Ver ejemplo de etiqueta <example>
Etiqueta <see>
Sintaxis:
<see cref="member"/>
Descripción:
Esta etiqueta nos permite poner la referencia hacía un elemento de programación en nuestro
código (namespace, clase), de manera que cuando el usuario de un clic en el elemento resaltado
se podrá obtener más información del miembro solicitado. Comúnmente puede ser utilizado para
obtener más información del tipo al cual estamos haciendo referencia. La etiqueta <see> permite
especificar un vínculo desde dentro del texto.
Utilice <seealso> para indicar el texto que desea que aparezca en una sección [Vea también]. El
atributo cref se puede asociar a cualquier etiqueta para proporcionar una referencia a un
elemento de código. El compilador comprobará si existe ese elemento de código. Si la
comprobación no tiene éxito, el compilador emite una advertencia. El compilador también
respeta cualquier instrucción using cuando busca un tipo descrito en el atributo cref.
Ejemplo: Ver ejemplo de etiqueta <example>
6. DOCUMENTACIÓN EXTERNA
Está formada por todos los documentos escritos que están fuera del programa y ayudan a
utilizarlo correctamente. En este tipo de documentación, se agrupan todos los manuales, guías
de referencia, libros de ayuda y demás escritos, que suelen entregarse con cada programa, de
manera que el usuario pueda aprender su manejo y consultar cualquier duda ante un problema
desconocido.
La documentación adecuada y completa, de una aplicación que se desea implantar, mantener y

actualizar en forma satisfactoria, es esencial en cualquier Sistema Informático, sin embargo,
frecuentemente es la parte a la cual se dedica el menor tiempo y se le presta menos atención.
PROGRAMACION I
La importancia de la documentación bien podría ser comparada con la importancia de la

existencia de una Póliza de Seguro; mientras todo va bien no existe la precaución de confirmar si
nuestra Póliza de Seguros está o no vigente. Siempre se debe documentar un sistema como si
estuviera a punto de irse al fin del mundo en el siguiente mes, para nunca volver. Si la
documentación del sistema es incompleta el diseñador continuamente estará involucrado y no
podrá moverse a otra asignación.
La documentación de un programa empieza a la vez que la construcción del mismo y finaliza justo
antes de la entrega del programa o aplicación al cliente. Así mismo, la documentación que se
entrega al cliente tendrá que coincidir con la versión final de los programas que componen la
aplicación.
Una vez concluido el sistema informático, los documentos guía que se deben entregar son:
 Manual o Guía Técnico

 Manual de Usuario o Guía de Uso
 Manual o Guía de instalación
 Manual o Guía de implementación
 Manual del administrador
6.1. MANUAL O GUÍA TÉCNICO

Refleja el diseño del proyecto, la codificación de la aplicación y las pruebas realizadas para su
correcto funcionamiento. Está diseñado para personas con conocimientos de informática,
generalmente programadores. Su principal objetivo es el de facilitar el desarrollo, corrección y
futuro mantenimiento de la aplicación de una forma rápida y fácil.
Esta Guía está compuesta por tres apartados claramente diferenciados:
 Cuaderno de Carga: donde queda reflejada la solución o diseño de la aplicación.

Está destinado únicamente a los programadores. Debe estar realizado de tal forma que
permita la división del trabajo
 Programa Fuente: incluye la codificación realizada por los programadores. Este documento
puede tener, a su vez, otra documentación para su mejor comprensión y puede ser de gran ayuda
para el mantenimiento o desarrollo mejorado de la aplicación. Este documento debe tener una
gran claridad en su escritura para su fácil comprensión.
PROGRAMACION I
 Pruebas: es el documento donde se especifican el tipo de pruebas realizadas a lo largo de todo

el proyecto y los resultados obtenidos.
Ya que este manual está dirigido al personal técnico responsable de corregir errores, y agregar o
modificar funciones en el sistema, debe incluir la documentación generada durante el análisis y
diseño del sistema. Estos documentos describen:
 La función del sistema mediante diagramas y descripciones breves de las actividades

principales. (Diagramas de Flujo o Flujogramas)
 Los datos, las relaciones entre los datos, las relaciones entre datos y funciones del
sistema. (Análisis del Problema)
6.2. MANUAL DE USUARIO O GUÍA DE USO
Contiene la información necesaria para que los usuarios utilicen correctamente la aplicación. Este
documento se hace desde la guía técnica, pero se suprimen los tecnicismos y se presenta de
forma que sea entendible para el usuario que no sea experto en informática. Un punto a tener
en cuenta en su creación es que no debe hacer referencia a ningún apartado de la Guía Técnica
y en el caso de que se haga uso de algún tecnicismo debe ir acompañado de un glosario al final
para su fácil comprensión.
Este documento sirve de guía sobre el uso del programa. Y debe contener lo siguiente:
 Índice
 Prefacio, con información sobre cómo usar el propio manual.
 Guía rápida sobre cómo usar las funciones principales del programa o sistema.
 Sección para la resolución de problemas.
 Sección de preguntas formuladas frecuentemente (FAQ)
 Información de contacto.
 Glosario.
6.3. MANUAL O GUÍA DE INSTALACIÓN
Debe dar todos los detalles acerca de cómo instalar el sistema en un entorno particular antes de
proceder a la instalación en sí, es conveniente tener un conocimiento de los requisitos de
hardware y software para instalar y usar el programa, debe incluir la configuración mínima de
hardware requerida por el sistema. Este Manual está dirigido al personal técnico responsable de
instalar y configurar inicialmente un sistema informático.
PROGRAMACION I
El manual se divide en:
● Requisitos de hardware y software: Características del hardware y software básico y/o

de aplicaciones, necesarios para hacer la instalación y la utilización del programa (o
sistema).
● Instalación: Detalla paso a paso el proceso de instalación del programa o sistema.
● Configuración: Explica los principales parámetros que deben inicializarse antes de usar el
sistema o programa.
6.4. MANUAL DE IMPLEMENTACIÓN
Contiene la información necesaria para implementar dicha aplicación. Dentro de este documento
se encuentran las instrucciones para la puesta en marcha del sistema y las normas de utilización
del mismo. Dentro de las normas de utilización se incluyen también las normas de seguridad,
tanto las físicas como las referentes al acceso a la información.
Con la documentación se pueden mantener y actualizar las soluciones tanto algorítmicas como
codificadas en un Lenguaje de Programación específico, logrando que se proporcione una
comunicación clara y rápida, que puede reducir costos en el almacenamiento, adiestramiento de
personal, adquisición de tecnologías y otros. Incluye la descripción de todas las actividades
necesarias para convertir un sistema anterior a otro nuevo sistema. Un sistema informático
podría necesitar ser actualizado o sustituido en forma total por un nuevo sistema. Entre las
actividades que debe incluir están:
● Cambiar software existente.

● Preparar o convertir datos existentes.
● Adquirir equipo informático (hardware y/o software).
● Hacer cambios físicos al edificio o ambiente donde se ubicará el sistema.
● Capacitar o reasignar al personal que operará el sistema.
● Cambiar procedimientos y métodos de trabajo.
● Garantizar la seguridad de los equipos y datos del sistema.
6.5. MANUAL DEL ADMINISTRADOR
Instructivo dirigido a la persona encargada de instalar, configurar y administrar un sistema

informático. Ya que el administrador se encarga de instalar, controlar los accesos, poner en
funcionamiento la solución, crear o modificar la configuración del sistema, capacitar sobre su uso
PROGRAMACION I
y solucionar problemas técnicos; el manual debe contener la información necesaria para realizar
dichas actividades.
Los manuales detallados anteriormente, se relacionan con un sistema informático y no con

soluciones compuestas de un solo programa; por lo tanto, durante este ciclo la Documentación
Externa de nuestras soluciones estará formada por:
 Planteamiento del problema

 Análisis del problema: Definición de:
- Variables de Salida
- Variables de Entrada
- Restricciones para datos de Entrada
- Procesos matemáticos
- Procesos lógicos
- Variables de proceso.
 Diagramas
Un sistema informático es un conjunto formado principalmente por los siguientes dos elementos
que interactúan entre sí con el fin de apoyar las actividades de una empresa o negocio:
 Equipo computacional o hardware necesario para que el sistema informático pueda

operar.
 Recurso humano que interactúa con el sistema informático, el cual está formado por las
personas que utilizan el sistema.
La Documentación Externa (Ozuna, 01), puede definirse como la agrupación de los siguientes
documentos:
Descripción del Problema, Nombre y datos del Autor, Descripción del Algoritmo (diagrama de
flujo o pseudocódigo), Manuales, Diccionario de Datos y Listado del Código Fuente. Se escribe en
cuadernos o libros, totalmente ajena a la aplicación en sí. Dentro de esta categoría también se
encuentra la ayuda electrónica.
Dentro de las técnicas estructuradas para el diseño y documentación del software se tienen: el
método HIPO, los diagramas de flujo, los diagramas Nassi-Schneiderman, los diagramas Warnier-
Orr y el pseudocódigo. Aquí es donde, el analista de sistemas transmite al programador los
requerimientos de programación. Durante esta fase, el analista también colabora con los
usuarios para desarrollar la documentación indispensable del software, incluyendo los manuales
PROGRAMACION I
de procedimientos. La documentación le dirá al usuario cómo operar él software, y así también,

qué hacer en caso de presentarse algún problema.
Método IPO: consta de un sistema de programación que contiene subsistemas, disminuye la

dificultad obtenida en el diseño de arriba hacia abajo ya que los componentes se pueden manejar
por separado.
Entrada Proceso Salida

Nombre del usuario a) Verificar que se ingrese Acceso al sistema
Clave del usuario tanto el nombre del
usuario como su clave.
b) Pegarse a la base de datos
c) Buscar el usuario
d) Comparar que las
contraseñas coincidan
Ejemplo de diagrama IPO
Diagrama de Flujo: guía visual que muestra el flujo del programa.
PROGRAMACION I
Ejemplo de diagrama de flujo
Diagrama N-S: es una técnica de especificación de algoritmos que combina la descripción textual,
propia del pseudocódigo, con la representación gráfica del diagrama de flujo. El diagrama N-S
cuenta con un conjunto limitado de símbolos para representar los pasos del algoritmo, por ello
se apoya en expresiones del lenguaje natural; sin embargo, dado que el lenguaje natural es muy
extenso y se presta para la ambigüedad, sólo se utiliza un conjunto de palabras “reservadas”.
Ejemplo de carta Nazzi
Diagrama Warnier Orr: es una técnica que utiliza una representación semejante a la de cuadros
sinópticos para mostrar el funcionamiento y organización de los elementos que conforman el
algoritmo. Son fáciles de leer y modificar y no tienen que completarse antes de ser útiles.
Básicamente, utiliza una notación de llaves para organizar los módulos.
Pseudo-Código: puede ser usado como un paso para desarrollar el código de programa, por lo
que no es un tipo particular de código. Es común en el campo informático, pero su falta de
estándar impide la aceptación de todos.
PROGRAMACION I
7. BIBLIOGRAFÍA
Microsoft. (2003 de 01 de 01). Microsoft Developer Network. Obtenido de
https://msdn.microsoft.com/es-es/library/aa291593(v=vs.71).aspx
Ozuna, M. d. (2016 de 08 de 01). Documentacion tecnica de un programa. Obtenido de

http://www.arqhys.com/general/documentacion-tecnica-de-un-programa.html
Wikimedia. (9 de Mayo de 2016). Wikilibros. Obtenido de

https://es.wikibooks.org/wiki/C_sharp_NET
8. GLOSARIO
Diagrama: es un gráfico que puede ser simple o complejo, con pocos o muchos elementos, pero
que sirve para simplificar la comunicación y la información sobre un proceso o un sistema
determinado.
Etiqueta: Marca o marcas que se dejan en un texto para que luego sean interpretadas,
generalmente para realizar alguna acción sobre el mismo texto marcado.
Manual: Contiene en forma explícita, ordenada y sistemática información sobre objetivos,

políticas, atribuciones, organización y procedimientos de los órganos de una institución; así como
las instrucciones o acuerdos que se consideren necesarios para la ejecución del trabajo asignado
al personal.
Sintaxis: Se entiende como el grupo de normas que marcan las secuencias correctas de los
elementos propios de un lenguaje de programación.
XML: es una adaptación del SGML (Standard Generalized Markup Language), un lenguaje que
permite la organización y el etiquetado de documentos. Esto quiere decir que el XML no es un
lenguaje en sí mismo, sino un sistema que permite definir lenguajes de acuerdo a las necesidades.

Virfia PRN115 U1 CT 1.2-1.2 Me

Hochgeladen von

Dokumentinformationen

Originaltitel

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

Virfia PRN115 U1 CT 1.2-1.2 Me

Hochgeladen von

Copyright:

Verfügbare Formate

UNIVERSIDAD DE EL SALVADOR EN LÍNEA

FACULTAD DE INGENIERÍA Y ARQUITECTURA

Las siguientes situaciones ilustran la necesidad de escribir programas fáciles de utilizar:

Aplicar las Técnicas de Documentación en el desarrollo de software.

Son funciones de un documento:

 Permitir la comunicación humana.

Un documento válido debe ser:

Original: de primera mano, fruto de un estudio o investigación.

La Documentación es la parte de la Programación que se encarga de escribir la “literatura”

Rapidez: los documentos pertinentes deben transmitirse al usuario interesado inmediatamente

Economía: el costo de la Documentación debe ser mínimo.

A continuación, se escriben algunas preguntas básicas orientadoras para la redacción de la

¿Cuándo introducir datos?

¿Qué tipo de datos?

¿Cuántos datos necesita introducir?

El mantenimiento de un programa, también se facilita mediante la Documentación, ya que,

Estandarización significa el uso de símbolos convencionales en los diagramas que describen el

4.1. VENTAJAS DE LA ESTANDARIZACIÓN

El desafío de la documentación interna es garantizar que se mantienen y actualizan los

Es una buena técnica de escritura de código fuente, adoptar el Estilo Camel1

● UpperCamel: cuando la primera letra de cada una de las palabras es mayúscula.

5.2. CONVENCIONES BÁSICAS PARA LA DOCUMENTACIÓN

● Antes de la implementación, quite todos los comentarios temporales o innecesarios, para

5.3. COMENTARIOS BÁSICOS

5.4. ETIQUETAS XML

Esta información se muestra en el Examinador de objetos y en el Informe Web de comentario de

Documentación de Métodos / Funciones

Específica el valor de retorno de una función. La etiqueta <returns> se debe utilizar en el

Sintaxis: <param name='name'>description</param>

La etiqueta <param> se usa para describir parámetros. Cuando se utiliza, el compilador

La etiqueta <example> permite especificar un ejemplo de cómo utilizar un método u otro

Ejemplo: Ver ejemplo de etiqueta <example>

Ejemplo: Ver ejemplo de etiqueta <example>

La documentación adecuada y completa, de una aplicación que se desea implantar, mantener y

La importancia de la documentación bien podría ser comparada con la importancia de la

 Manual o Guía Técnico

6.1. MANUAL O GUÍA TÉCNICO

Esta Guía está compuesta por tres apartados claramente diferenciados:

 Cuaderno de Carga: donde queda reflejada la solución o diseño de la aplicación.

 Pruebas: es el documento donde se especifican el tipo de pruebas realizadas a lo largo de todo

 La función del sistema mediante diagramas y descripciones breves de las actividades

6.2. MANUAL DE USUARIO O GUÍA DE USO

6.3. MANUAL O GUÍA DE INSTALACIÓN

El manual se divide en:

● Requisitos de hardware y software: Características del hardware y software básico y/o

6.4. MANUAL DE IMPLEMENTACIÓN

● Cambiar software existente.

6.5. MANUAL DEL ADMINISTRADOR

Instructivo dirigido a la persona encargada de instalar, configurar y administrar un sistema

Los manuales detallados anteriormente, se relacionan con un sistema informático y no con

 Planteamiento del problema

 Equipo computacional o hardware necesario para que el sistema informático pueda

de procedimientos. La documentación le dirá al usuario cómo operar él software, y así también,

Método IPO: consta de un sistema de programación que contiene subsistemas, disminuye la

Entrada Proceso Salida

Diagrama de Flujo: guía visual que muestra el flujo del programa.

Ejemplo de diagrama de flujo

Ejemplo de carta Nazzi

Ozuna, M. d. (2016 de 08 de 01). Documentacion tecnica de un programa. Obtenido de

Wikimedia. (9 de Mayo de 2016). Wikilibros. Obtenido de

Manual: Contiene en forma explícita, ordenada y sistemática información sobre objetivos,

Das könnte Ihnen auch gefallen