You are on page 1of 245

Documentacin gil

Documentacin gil
Una gua del patrn de
La produccin de documentos ligeros para
Proyectos de Software

Andreas Rping
Copyright 2003 por John Wiley & Sons Ltd, el atrio, Puerta del Sur, Chichester,
West Sussex PO19 8SQ, Inglaterra
Telfono (+44) 779 777 1243
E-mail (para pedidos y consultas de servicio al cliente): cs-books@wiley.co.uk Visita nuestra

pgina inicial en www.wileyeurope.com o www.wiley.com

Todos los derechos reservados. Ninguna parte de esta publicacin puede ser reproducida, almacenada en un sistema de recuperacin o transmitida en cualquier forma o por
cualquier medio, electrnico, mecnico, de fotocopiado, de grabacin, de exploracin o de otra manera, excepto bajo los trminos del Derecho de Autor, Diseos y Patentes de 1988
o bajo los trminos de una licencia expedida por la copyright Licensing Agency Ltd, 90 Tottenham Court Road, Londres W1T 4LP, Reino Unido, sin el permiso por escrito del editor.
Las solicitudes al Editor deben dirigirse al Departamento de Permisos, John Wiley & Sons Ltd, el atrio, Puerta del Sur, Chichester, West Sussex PO19 8SQ, Inglaterra, o por correo
electrnico a permreq@wiley.co.uk, o por fax al (+44 ) 1243 770620.

Esta publicacin est diseada para proporcionar informacin precisa y fidedigna relacionada con el tema en cuestin. Se vende en el entendimiento de que la editorial no
se dedica a prestar servicios profesionales. Si se requiere un asesoramiento profesional u otra asistencia de expertos, los servicios de un profesional competente deben ser
buscados.

Otros Wiley Editorial fi cinas


John Wiley & Sons Inc., 111 River Street, Hoboken, NJ 07030, EE.UU. Jossey-Bass, 989 Market Street, San Francisco, CA
94103 hasta 1741, EE.UU. Wiley-VCH Verlag GmbH, Boschstr. 12, D-69469 Weinheim, Alemania John Wiley & Sons Ltd
Australia, 33 Park Road, Milton, Queensland 4064, Australia John Wiley & Sons (Asia) Pte Ltd, 2 Clementi Loop # 02-01, Jin
Xing Distripark, Singapur 129809 John Wiley & Sons Ltd. Canad, 22 Worcester Road, Etobicoke, Ontario, Canad M9W 1L1

Wiley tambin publica sus libros en una variedad de formatos electrnicos. Parte del contenido que aparece en la impresin puede no estar disponible en los libros electrnicos.

Biblioteca del Congreso de datos Catalogacin en la Publicacin

Rping, Andreas.
documentacin gil: una gua patrn para la produccin de documentos ligeros para

proyectos de software / Andreas Rping.

pag. cm.

ISBN 0-470-85617-3 (Papel:. Alq papel)


1. Los sistemas de fabricacin flexible. 2. El diseo del sistema. I. Ttulo. TS155.65.R87

2003

005.1'5-DC21
2003011756

Catalogacin Biblioteca Britnica de datos de publicacin

Un registro de catlogo de este libro se encuentra disponible en la Biblioteca Britnica

ISBN 0-470-85617-3
Compuesta en Garamond Luz y Frutiger por WordMongers Ltd, Treen, Cornualles TR19 6LG, Inglaterra impreso y encuadernado en Gran

Bretaa por Biddles Ltd., Guildford y Kings Lynn es un libro impreso en papel libre de cido con responsabilidad fabricado a partir de una

silvicultura sostenible, en el que al menos dos rboles se plantan para cada uno utilizado para la produccin de papel.
Contenido

Prefacio ix

Prefacio xi

Expresiones de gratitud xvii

Introduccin 1

antecedentes del proyecto 11

1 Encontrar los temas correctos 19


Los lectores de destino 24
La informacin centrada 26
Requisitos de documentacin individuales 28
Cartera documentacin 30
Centrarse en a largo plazo Relevancia 34
Especificacin como un esfuerzo conjunto 36
Fundamentos de diseo 39
El panorama 40
La separacin de descripcin y evaluacin 42
Los ejemplos realistas 44
Informes de experiencia 46
vi Contenido

2 Estructuracin de documentos individuales 61


La informacin estructurada 66
Diagramas juiciosas 70
Tablas sin ambigedades 73
Directrices para los lectores 75
Thumbnail Sketches 77
Referencias trazables 78
Glosario 79
Historia del documento 81
Informes de experiencia 82

3 diseo y la tipografa 93
Texto en el 50% de una pgina 98
Dos alfabetos por lnea 100
120% Interlineado 102
dos Tipos de letra 104
El uso cuidadoso de las modificaciones de tipo 106
Sentencia cuidado y sombreado 108
La colocacin adyacente 109
Pginas coherentes 111
Informes de experiencia 112

4 Infraestructura y Organizacin Tcnica 117


Paisaje documento 120
Archivo de documentos 123
wiki 125
Cdigo-comentario de proximidad 126
De fcil lectura-Medios 128
Separacin de Contenido y disposicin 131
Fuente nica y Objetivos Mltiples 133
Importacin por referencia 136
La separacin de procesamiento e impresin 138
plantillas de documentos 139
pocas herramientas 142
Los cambios anotado 144
Notificacin sobre la actualizacin 145
Reorganizacin a peticin 147
Contenido vii

Informes de experiencia 149

Gestin 5 y Aseguramiento de la Calidad 159


Una actividad distinta 161
Un responsable Autor 164
Documentacin continua 166
La escritura y la reflexin 168
revisin Cultura 170
Revisin Antes de entrega 174
Crtica de consumidor 175
Una vista distante 177
informacin del mercado 179
Gestin del conocimiento 180
Informes de experiencia 182

Observaciones finales 193

patrn de miniaturas 197


Encontrar los temas correctos 197
La estructuracin de los documentos individuales 198
Diseo y la tipografa 200
Infraestructura y Organizacin Tcnica 201
Gestin y Aseguramiento de la Calidad 203

Glosario 205

referencias 211

ndice 221
Prefacio

Como dice Jerry Weinberg en su texto clsico La psicologa de la Programacin de Computadoras:

La documentacin es el aceite de ricino de la programacin. Los gerentes piensan que es bueno para los
programadores, y los programadores lo odio! El valor de la documentacin slo debe realizarse si la
documentacin est bien hecho. Si est mal hecho, ser peor que no tener la documentacin en absoluto.

Nada en el manifiesto gil ( http://agilemanifesto.org/ ) estados no hagas ninguna documentacin ', pero ya
que muchos desarrolladores tienen una resistencia gentica a cualquier forma de escritura que no
se expresa en un lenguaje de programacin, se han estrechado el siguiente principio a sus pechos
colectivos:

... hemos llegado a valorar: software de Trabajo ms de una documentacin completa

y proclamado al mundo que la documentacin est fuera.

Mi carrera de desarrollo de software ha sido sobre todo en grandes proyectos, como la que
desarroll el software para el Boeing 777. No hay manera de que los proyectos similares, que
pueden prescindir de la documentacin. Yo sera el primero en admitir que el proyecto 777 y todos
los dems que he visto primer plano se podran haber hecho mejor. Podran haber sido completado
tan bien de una manera menos pesada. No slo creo que siempre hay margen de mejora, pero
tambin creo que hay que esforzarse continuamente para mejorar

- especialmente en proyectos de seguridad crtica. As que o bien se admite que los proyectos de esta magnitud son
irremediablemente 'no gil', o estamos de acuerdo en que, cuando es apropiado
- es decir, cuando se aade valor - hay una necesidad de documentacin. Yo voto por este ltimo.
x Prefacio

Ahora, sin embargo, nos enfrentamos al dilema - qu significa eso en un proyecto gil? Puede un proyecto
realmente seguir los principios giles y todava producir documentacin? Esta es la pregunta Andreas Rping
aborda en este libro. Andreas ha documentado sus experiencias de aventuras de proyectos exitosos y no
exitosos con la documentacin. l comparte una serie de encuentros con diversos proyectos pequeos: a,
vieja tecnologa a gran nueva, que abarca los ltimos 12 aos. Me he convertido en un creyente en el poder
de las historias - no hay nada mejor que escuchar lo que otros han hecho. Cuando compartimos nuestros
xitos y fracasos, todos aprendemos. Hay un montn de buenas historias aqu, todos los proyectos reales,
con algunas lecciones aprendidas instructivos y algunas trampas que deben evitarse. Andreas hace un buen
trabajo de explicar las ventajas y desventajas: cuando la documentacin es mejor que cara a cara, cuando en
lnea es mejor que la copia impresa, cuando diagramas son ms tiles que el texto. En una discusin cercano
y querido a mi corazn, que tambin muestra cmo los impactos de documentacin del cliente. Toda esta
informacin se captura como un conjunto de patrones relacionados. Al igual que las historias, soy un creyente
en el poder de los patrones. He escrito muchos m mismo y puedo dar fe de que proporcionan orientacin en
una forma til. Andreas proporciona informacin su fi ciente para que nosotros aplicamos esta orientacin y
se benefician de su experiencia. Esto es algo til, prctico.

El libro sigue sus propios principios. Es ligero y presenta las ideas tiles sin tener que sobrecargar
el usuario. Es fcil de leer y entender y presenta soluciones que se basan claramente en la
experiencia real de proyecto. Me encontr asintiendo o inclinando la cabeza en la consternacin
mientras lea algo sorprendente. He aprendido mucho leyendo este pequeo libro, y estoy seguro
de que tambin lo har.

Linda Rising
Prefacio

Si usted trabaja en la industria del software, usted sabr que la documentacin que juega un papel importante en
muchos proyectos. Entre otras cosas, los documentos describen los requisitos del usuario, arquitecturas de
software, las decisiones de diseo, cdigo fuente y los problemas de gestin.

No puede haber una gran cantidad de valor en tales documentos. La documentacin puede contribuir al xito de
un proyecto, facilitando la informacin necesaria a disposicin de los miembros del equipo. Los documentos se
pueden preservar el conocimiento dentro de un equipo, y evitar que el equipo re-inventar cosas cuando salen de
los miembros del equipo y las personas se suman. Los documentos se pueden capturar la experiencia adquirida
en un proyecto y ponerlo a disposicin de los proyectos futuros. Cuando el conocimiento se ha comprometido con
el papel, no se puede perder.

Sin embargo, vivimos en la era de la informacin. Estamos rodeados de mucha informacin, a menudo
demasiado. Puede llegar a ser difcil de filtro de lo que realmente necesitamos. Proyectos veces sufren de
demasiados documentos y documentos demasiado tiempo. Si este es el caso, los miembros del equipo en
busca de informacin especfico fcilmente se pierden. Algunas cosas son tambin mucho mejor comunican
cara a cara a travs de documentos escritos. El exceso de documentacin es tan malo como no hay
documentacin en absoluto.

Tambin es difcil mantener los documentos al da cuando sus sujetos se someten a cambio. Conservacin
de los documentos al da es especialmente difcil cuando un proyecto est ocupado y muchas otras cosas
requieren atencin. Pero los documentos obsoletos pueden conducir fcilmente a los lectores equivocadas
pista - documentos obsoletos a menudo hacen ms dao que bien. Este libro tiene una gil aproximacin a
la documentacin - un enfoque que es a la vez ligero y su fi ciente, en la misma lnea que los enfoques
giles a
xii Prefacio

desarrollo de software que recientemente han llegado a ser populares (Cockburn 2001, Highsmith 2002,
Ambler 2002).

Este libro presenta una coleccin de patrones - directrices que ofrecen soluciones a los problemas
recurrentes an mltiples caras de la documentacin. Estos patrones se rigen por los siguientes
principios generales:

La documentacin del proyecto es ms eficaz cuando es ligero, sin ningn tipo de documentos innecesarios,
sin embargo, que proporciona toda la informacin relevante para los lectores.

Los documentos que se consideren necesarios slo pueden resultar tiles si son de alta calidad:
informacin precisa y actualizada, de fcil lectura y legible, concisa y bien estructurada.

Herramientas y tcnicas son tiles slo si facilitan la produccin de documentos de alta


calidad y hacer que su organizacin y mantenimiento ms fcil.

El proceso de documentacin debe ser e fi ciente y directo, debe adaptarse a los requisitos
del proyecto individual y debe ser capaz de responder al cambio.

Es importante destacar que este libro no prescribe un mtodo estndar que pretende resolver todos los
problemas asociados con la documentacin del proyecto de software. En primer lugar, un procedimiento de
este tipo es prcticamente imposible, ya que no hay dos proyectos tienen los mismos requisitos de
documentacin. En segundo lugar, un mtodo de peso pesado es lo ltimo que querra proponer - un fl
integracin global super mtodo de documentacin 'estndar' sera demasiado inflexibles e implicara
demasiada burocracia para ser til. Ciertamente, no sera gil.

Este libro se centra ms bien en los elementos y procesos que en repetidas ocasiones se pueden
encontrar en buena documentacin del proyecto, y que expresan una actitud gil. Tales elementos y
procesos se han formado en los patrones que se pueden utilizar para disear la documentacin que fi
cios de su proyecto individual mejor, y que contribuye a la experiencia realizada en su organizacin.

Alcance Este libro est dirigido a personas que trabajan en la industria del software y cuyo trabajo incluye la redaccin de la
documentacin del software en algn momento. Esto es cierto para la mayora de los ingenieros de software,
diseadores, consultores y gestores. Si pertenece a alguno de estos grupos, entonces este libro es para usted. 1
Prefacio xiii

Tal vez te gusta la documentacin, o tal vez usted lo ve como una carga. En cualquier caso, este libro
le dar consejos sobre cmo centrarse en lo que es importante en la documentacin, se debe hacer
que su proceso de documentacin ms e fi ciente, y que debera conducir a mejores resultados.

Puede utilizar la documentacin gil en diferentes tipos de proyectos. En primer lugar, la documentacin
gil est dirigido a proyectos de desarrollo de software. Los proyectos de desarrollo tienen un objetivo
general de la distribucin de software de trabajo que satisface los requisitos fi que la del cliente. En un
proyecto de desarrollo, la documentacin es un medio, no un fin: la documentacin se supone para ayudar
al equipo a cumplir sus tareas. Este libro recomienda la documentacin que sea lo ms ligero posible, pero
no ms claro.

proyectos de consultora tambin estn dentro del alcance de este libro. proyectos de consultora de colocar
ligeramente diferentes requisitos sobre la documentacin de los proyectos de desarrollo, ya que los
proyectos de consultora a veces tienen la documentacin, en lugar de software, como el resultado del
proyecto deseado. proyectos de consultora puede bene fi ciarse de un enfoque gil, ya que este
planteamiento hace que el proceso de documentacin ms e fi ciente y los documentos resultantes ms
compacto y sencillo.

Organizacin Antes de presentar los patrones reales para la documentacin gil, este libro
comienza con algunas observaciones preliminares sobre el desarrollo gil y sobre los patrones. Si
desea leer sobre la Manifiesto gil y cmo se relaciona con la documentacin, esta introduccin ser til
para usted. Si desea aprender qu patrones son y cmo se pueden utilizar, tambin encontramos
respuestas en la introduccin. Una seccin que sigue describe brevemente los proyectos en los que se
observaron los patrones en este libro. La coleccin real de los patrones se encuentran en los cinco
captulos principales del libro, cada uno de los cuales se ocupa de un tema en particular de la
documentacin del proyecto de software. Especficamente, los principales captulos se refieren a las
siguientes reas:

1. Encontrar los temas correctos

La documentacin es importante: algunos aspectos de un proyecto requieren documentacin


desesperadamente, mientras que otros no lo hacen. Entonces, qu documentos son necesarios en su
proyecto, y qu temas deberan cubrir? Qu nivel de detalle es

1. El libro, sin embargo, no se trata de la clase de los manuales de usuario que vienen, por ejemplo, con paquetes de software estndar, guas
de instalacin de software o similares, ni es el libro dirigido a la documentacin que se produce por los escritores tcnicos profesionales.
xiv Prefacio

necesario? Qu documentos son quizs innecesario? Este captulo presenta algunas pautas
sobre cmo Para averiguar qu documentacin requiere su proyecto.

2. La estructuracin de los documentos individuales

documentos bien estructurados dan a los lectores una mejor y ms rpido acceso a la informacin de los
documentos pobremente estructurados. Pero qu aspecto tiene una estructura de documento como? Cmo
puede asegurarse de que sus lectores fi fcil encontrar la informacin que est buscando? Este captulo
ofrece sugerencias sobre cmo aumentar la legibilidad de los documentos del proyecto.

3. Diseo y la tipografa

La legibilidad es una cosa, la legibilidad es otro. Cmo se puede documentar la disposicin apoyar la capacidad
del lector para comprender el contenido de un documento de forma rpida y fiable? Cmo puede una
disposicin tal puede lograr con los procesadores de texto estndar? Este captulo le indica cmo mejorar la
apariencia de sus documentos fcilmente.

4. Infraestructura y Organizacin Tcnica

En este captulo se habla de cmo se puede gestionar sus documentos del proyecto. El captulo comienza con
las cuestiones de organizacin: cmo se puede obtener una visin general de la documentacin del proyecto?
Se supone que los documentos se imprimen en papel? Qu hay de documentacin en lnea, que se est
convirtiendo cada vez ms popular? La solucin de esos problemas de manera rpida nos conduce a temas
ms tcnicos: cmo se pueden procesar y almacenar documentos? Cmo puede asegurarse de que los
documentos individuales se pueden encontrar fcilmente? Qu medidas deben tomarse para hacer la
documentacin del proyecto fcil de mantener? Qu herramientas son necesarias para esto?

5. Gestin y Aseguramiento de la Calidad

Los problemas de gestin de direcciones ltimo captulo como el presupuesto, responsabilidades y prioridades,
en lo que se refiere a la documentacin del proyecto. Las preguntas que debe hacer aqu son: qu aspecto
tiene un proceso de documentacin e fi ciente similares, o, cmo se puede evitar la burocracia? Siendo medios
giles poniendo a las personas en primer plano, por lo que este captulo se hace hincapi en el papel que juegan
las personas en el proceso de documentacin y subraya la importancia de la retroalimentacin y reflexin.
Prefacio xv

Cmo leer este Hay diferentes maneras de leer este libro. Usted no necesariamente tiene que leer el libro en orden
libro secuencial:

Si usted est interesado en una visin rpida, slo tiene que ir a travs de cada patrn con
rapidez y leer las secciones en negrita. Estos bocetos forma en miniatura que le dan una
impresin general del patrn real. Adems, un resumen de todas estas miniaturas se da al
final del libro.

Leer los patrones completos si desea obtener una visin ms profunda, y particularmente si usted
est interesado en la lgica de los patrones individuales.

Comience con los informes de la experiencia, si desea tomar un viaje a travs de varios proyectos del
mundo real. Los informes explican cmo se utilizaron los patrones en esos proyectos.

Es una buena idea para combinar estos enfoques. Puede comenzar con las miniaturas, para que pueda
obtener una visin general de lo que el libro tiene en el almacn, y leer los patrones completos cuando se
convierte interesado en los detalles o en el fondo de un modelo. A continuacin, puede utilizar las miniaturas
como una lista de control cuando se trabaja en la documentacin de su proyecto, utilizando los patrones
completos cuando se trata de cuestiones ms detalladas. Alternativamente, se puede comenzar con los
informes de la experiencia, y seguir las referencias a los patrones individuales cada vez que sienta un patrn
es de particular inters para usted. Si usted est interesado en algunos temas ms que otros, puede
concentrarse en los captulos que son de particular inters para usted. Los punteros de vez en cuando se
refieren a un material relacionado en otros captulos.

Este es un libro relativamente corto: es intencional de peso ligero y tiene como objetivo seguir el
enfoque que se propone - usted no tiene que leer muchos cientos de pginas. Muchos de los patrones
de fi cio en dos o tres pginas, y puede utilizar las imgenes en miniatura, si todo lo que necesita es un
breve resumen. No le tomar mucho tiempo para que se familiarice con un enfoque gil hacia la
documentacin de los proyectos de software. Me gustara invitarle a este enfoque con el objetivo de
hacer ms eficaz la documentacin para autores y lectores por igual. Estoy interesado en recibir sus
comentarios sobre este libro. Si usted tiene algn comentario, no dude en contactar conmigo en rueping@acm.org
.

Andreas Rping
Expresiones de gratitud

proyecto Mis primeras ideas sobre la documentacin gil (aunque no me refiero a l como tal en el momento)
gracias datan de hace varios aos a un momento en que yo estaba trabajando en FZI (Forschungszentrum
Informatik, Centro de Investigacin de Tecnologa de la Informacin) en Karlsruhe, Alemania. Durante
un par de proyectos de investigacin y varias colaboraciones industriales, he tenido la oportunidad de
aprender mucho sobre lo que caracteriza a una buena documentacin del proyecto. Pero no haba
ms que esto: el espritu de equipo entre el grupo me permiti disfrutar de esos aos mucho. Mi
agradecimiento a todos en el grupo, especialmente Gerhard Goos, Noel Lewerenzt, Simone Rehm,
Franz Weber, Dieter Neumann, Walter Zimmer, Thomas Lindner, Eduardo Casais, Annette Ltzbeyer,
Achim Weisbrod, Helmut Melcher, Oliver Ciupke, Benedikt Schulz, Rainer Neumann, Artur Brauer, Jrn
Eisenbiegler, Markus Bauer y Holger Br.

Mi comprensin de una buena documentacin se re fi ne cuando, unos aos ms tarde, me un SD


y software de diseo y gestin m AG, Alemania. Tuve la oportunidad de ver en la documentacin
producida en varios proyectos en los que particip. Muchos de los patrones incluidos en este libro
me llam la atencin cuando se aplicaron con xito en proyectos sd & m. Agradecimiento a mis
colegas por ser un buen equipo, por la colaboracin fructfera largo de muchos proyectos y para
muchas discusiones interesantes. En los ltimos aos, EuroPLoP - la conferencia europea sobre
patrones de software - ha sido un excelente foro para la discusin de todo tipo de temas en torno a
los patrones, para m y para los dems. Gracias a todo el mundo con el que yo estaba feliz de
colaborar en nuestros esfuerzos para organizar la conferencia, especialmente Frank Buschmann,
Jens Coldewey, Martine Devos, Paul Dyson, Jutta Eckstein, Kevlin Henney, George Platts, Didi
Schtz y Christa Schwanninger.
xviii Expresiones de gratitud

EuroPLoP result ser particularmente til cuando present documentos sobre diversos aspectos de la
documentacin. En primer lugar, me gustara agradecer a los que actu como pastores de mis
papeles: Ken Auer, Ward Cunningham, James Noble y Charles Weir. Sus comentarios y sugerencias
para mejorar tuvieron una influencia duradera sobre los patrones que lo haran en este libro. Por otra
parte, muchas personas ofrecen informacin valiosa y un montn de buenas ideas en los talleres
EuroPLoP. Son demasiados para nombrar en persona, pero su ayuda fue muy apreciado.

Un taller sobre 'Patrones de Gestin de Documentacin Liviana' en la conferencia de OT 2002 en


Oxford tambin genera ideas tiles. Gracias a todos los participantes.

Cuando puse el manuscrito de este libro juntos, varias personas se ofrecieron para trabajar como
colaboradores. Scott Ambler, Wolfgang Keller, Klaus Marquardt, Linda Rising, Peter Sommerlad, Markus
Vlter y Egon Wuchner tomaron el tiempo de leer el proyecto, ofrecieron su visin e hicieron valiosas
sugerencias para mejorarlo. Este libro tiene pro fi ciado mucho de su generosa ayuda. Varias personas han
proporcionado una gran cantidad de apoyo durante todo el proceso de publicacin. En primer lugar, me
gustara dar las gracias a Gaynor Redvers-Cordero de John Wiley & Sons por su trabajo como editor de
este libro. Ella proporcion una gran cantidad de ayuda en hacer el libro cobre vida. Gracias tambin a
Karen Mosman por su apoyo en la etapa temprana del proceso de publicacin, a Jonathan Shipley para el
cuidado de muchos detalles de la organizacin, y Juliet Booker por su trabajo como el editor de la
produccin. Por ltimo, pero no menos importante, me gustara dar las gracias a Steve Rickaby de
WordMongers para la conduccin suave a travs de la etapa de correccin de estilo. Este fue un proceso
muy agradable que dio lugar a un debate fructfero sobre el contenido, el lenguaje y el diseo del libro.

familia Estoy feliz de reconocer que este libro tiene tambin pro fi ciado enormemente de personas que no
gracias estaban directamente involucrados. Mis fi nales gracias salen a Gerhard, Hiltrud, Jutta, Sven-Folker,
Magnus, Nils Johann y Mareike para el estmulo, apoyo y esos momentos de equilibrio que usted
necesita cuando usted pasa por el proceso de escribir un libro.
Introduccin

gil documentacin gil ha prestado su nombre de las ideas de Desarrollo gil de Software . desarrollo
desarrollo gil de software fue originalmente propuesto por el
Agile Alliance - un grupo de 17 profesionales de software que primero se reuni en febrero de 2001
para recoger ideas para mejores formas de desarrollo de software. Estas ideas se describen en el Manifiesto
gil , que se puede encontrar en la web ( www.AgileAlliance.org ) y que tambin se cita en una serie de libros
(Cockburn 2001, Ambler 2002, Highsmith 2002). Aqu est la parte central de lo que dice el manifiesto
gil:

Los individuos y las interacciones sobre los procesos y herramientas

software yque
hacindolo trabajaa sobre
ayudando unaloamplia
que otros hagan.documentacin
A travs de este trabajo hemos llegado a valorar:
colaboracin con el cliente durante la negociacin del contrato

Respondiendo al cambio sobre seguir un plan


caractersticas diferentes. Todos estos nos estn descubriendo mejores formas de desarrollar software
Es decir, mientras hay valor en los elementos de la derecha, valoramos los elementos de la izquierda ms.

por varios mtodos propuestos por diferentes personas, que se aplican en diferentes contextos y tienen
El manifiesto contina con una serie de declaraciones ms detalladas y recomendaciones
concretas.

El desarrollo gil no es un mtodo espec fi co de desarrollo de software. El desarrollo gil est compuesto
2 Introduccin

mtodos tienen en comn, sin embargo, el hecho de que se centran en los valores fundamentales expresadas
en el manifiesto.

Algunos de los mtodos giles ms conocidos han sido descritos en los libros:

En su libro sobre Desarrollo gil de Software ( Cockburn 2001), Alistair Cockburn habla sobre el papel
central que desempea el trabajo en equipo en proyectos de desarrollo de software, y acerca de los
problemas de comunicacin que surgen en los proyectos de desarrollo de diferentes tamaos y en
diferentes niveles de rigor.

El libro de Jim Highsmith en Desarrollo de software adaptativo ( Highsmith


2000) considera los problemas de desarrollo de software desde la perspectiva de los sistemas
adaptativos complejos. Su nuevo libro sobre Los ecosistemas desarrollo gil de software ( Highsmith
2002) ofrece una visin general de los principios de desarrollo gil, e incluye entrevistas con
varias figuras notables de la comunidad gil.

libro de Scott Ambler sobre Modelado gil ( Ambler 2002) se refiere a la parte de modelado del
proceso de desarrollo de software. En l se detallan las prcticas que conducen a la
modelizacin eficaz y ligero, con especial nfasis en los aspectos humanos del desarrollo de
software.

Programacin extrema ( Beck 2000) fue propuesto por Kent Beck. XP, ya que generalmente se le conoce,
es un mtodo gil centrada en la programacin en su contexto social. XP da la bienvenida a los requisitos
cambiantes y pone mucho nfasis en el trabajo en equipo.

Otro mtodo es gil scrum ( Schwaber Beedle 2001), presentada por Ken Schwaber, Michael
Beedle y Jeff Sutherland, que dibujar en la importancia de la auto-organizacin y la reflexin.

Mara de Poppendieck prximo libro sobre Desarrollo magra


(Poppendieck 2003) describe una serie de principios de pensamiento lean, dirigidas a lderes
de desarrollo de software.

A medida que el manifiesto gil es todava bastante nuevo, podemos esperar que los mtodos ms giles de

desarrollo de software que surjan en un futuro prximo. Qu papel juega la documentacin en un proyecto gil?

El papel de la
documentacin La primera cosa a entender es fi parece que la documentacin sobre el lado derecho de las
declaraciones de valor en el manifiesto gil. Esto significa, en resumen, que la mejor documentacin en el
mundo hay excusa si el proyecto se supone que debe entregar el software, pero no lo hace.
Introduccin 3

Esto no significa, sin embargo, que la documentacin es generalmente poco importante o que la
documentacin no se estipule.

Vamos a echar un vistazo a lo que los autores de algunos de los mtodos giles tienen que decir acerca de la
documentacin:

Alistair Cockburn recomienda que la documentacin sea 'la luz, pero su fi ciente' (Cockburn
2001). Se introduce el Cristal familia de metodologas, que est dirigido a proyectos de
diferente tamao y criticidad. los Cristal
metodologas requieren documentacin que se cree, pero el proyecto individual decidir lo
que la documentacin debe consistir.

libro de Scott Ambler sobre Modelado gil ( Ambler 2002) incluye un captulo dedicado por
completo a la documentacin. En este captulo se denomina Desarrollo gil , al igual que este libro.
captulo y en el captulo 1 de este libro de Scott Ambler eran esfuerzos paralelos. Siguen
diferentes estilos de presentacin, pero llegan a conclusiones similares. Scott Ambler compara el
enfoque gil a la documentacin con 'viajar ligero': a 'crear apenas suficientes modelos y
simplemente la documentacin suficiente para sobrevivir'.

Jim Highsmith, en Los ecosistemas desarrollo gil de software ( Highsmith


2002), nos advierte de no producir la documentacin para el bien de la documentacin, pero pide un
equilibrio: 'Documentacin, con moderacin, ayudas para la comunicacin, mejora la transferencia de
conocimientos, conserva la informacin histrica, y ful fi ls gubernamentales y los requisitos legales'.

Mi opinin es que un enfoque fi ciente luz pero-SUF es favorable por dos razones. En primer lugar, este
enfoque evita que el equipo del proyecto de gastar innecesariamente grande esfuerzo de documentacin.
En segundo lugar, pero suf-luz de la documentacin deficiente es ms accesible, y por lo tanto ms til,
para un equipo que voluminosa documentacin. Creo que Scott Ambler hace la pregunta correcta: 'Qu le
gustara tener, un documento sistema de 2.000 pginas que es probable que tenga un nmero signi fi cativo
de errores en el mismo, o una de 20 pginas, visin general de alto nivel' (Ambler 2002)

Ciertamente, la documentacin detallada a veces es necesario, pero por lo general los documentos
ms concisos y accesibles resonar ms entre los lectores. Detalles menudo cambian ms
rpidamente que la documentacin puede ser actualizado, y se comunican mejor cara a cara. (Hay
ms en escritos, en lugar de cara a cara, la comunicacin al comienzo del captulo 1.)
4 Introduccin

utilidad de la
documentacin

cantidad de documentacin

Figura 1. La utilidad de documentacin

La Figura 1 demuestra la relacin entre la cantidad de documentacin y su utilidad. Ms all de un


cierto punto, la utilidad de la documentacin disminuye cuando se aade ms informacin, porque
hallazgo informacin relevante se vuelve ms y ms di fi culto como la cantidad total de los
aumentos de documentacin.

Creo que puedo resumir esto diciendo que la calidad es ms importante que la cantidad en la
documentacin del proyecto. Un cierto nivel de detalle y amplitud es necesario - y depende en gran
medida del proyecto individual - pero son los documentos concisos que ms contribuyen a la
comunicacin en un equipo de proyecto. El esfuerzo que se puede ahorrar mediante la produccin de ligero
documentacin es mejor gastado en el calidad de los documentos que usted cree, por lo que esos
documentos precisa, actualizada y bien organizado.

La gente a veces la impresin de que, en un contexto gil, no slo es la documentacin ligera


preferencia sobre una amplia documentacin, sino tambin que la calidad no es tan importante.
Creo que esto es un error, y claramente no estoy de acuerdo. Si decide que un documento es
necesario, entonces debe tener un propsito, de lo contrario no tomar la decisin de crearlo. Sin
embargo, para cumplir fi l tal efecto, una cierta calidad es esencial.

Como con tantas otras cosas, se puede optar por hacer algo o puede optar por no hacerlo, pero si
decide hacerlo, entonces lo mejor es hacerlo 'derecho'.
Introduccin 5

Los patrones en este libro invitan a lidiar con la documentacin de una manera gil. No prescriben un
proceso estricto, pero ofrecen las mejores prcticas para de fi nir la cantidad correcta de la
documentacin en su proyecto, y para hacer que la documentacin florecer.

Patrones Cules son los patrones? Dejame explicar.

Este libro se ocupa de una variedad de preguntas acerca de la documentacin. Qu documentacin es


necesaria y til? Qu temas deben ser cubiertos? Cmo deben estructurarse documentos individuales?
Cmo puede la documentacin del proyecto en su conjunto se organizar, y qu herramientas son
necesarias para hacerlo? Cmo se puede organizar el proceso de documentacin?

Si usted ha sido responsable de los aspectos de la documentacin de un proyecto de software, es probable


que haya enfrentado al menos algunas de estas preguntas. Estas preguntas no son nuevas - el que
contribuye a la documentacin de un proyecto de software se enfrenta a ellos una y otra vez.

Acecho detrs de estas preguntas son problemas recurrentes que tienen soluciones recurrentes. Estas
soluciones se repiten, o patrones, se pueden utilizar como directrices para la documentacin de los proyectos
futuros. UN patrn en este sentido es esencialmente un bien probada par problema-solucin, presentada en una
forma estructurada. Los usuarios pueden buscar patrones para sus problemas particulares, aplicar las
soluciones, y por lo tanto recurrir a la experiencia en general disponible.

De hecho, un patrn es un poco ms que esto. Un buen patrn tambin describe la


efectivo que estn asociados con un problema - todos aquellos temas que influyen o limitan las posibles
soluciones. Un patrn por lo tanto, no slo se presenta una solucin, sino que tambin ofrece la razn de ser
de esa solucin.

Por ltimo, los patrones normalmente no estn solos. Un solo patrn resuelve ningn problema, pero cuando nos
acercamos a un tema en su totalidad, ms a menudo que no nos enfrentamos a una serie de problemas
relacionados. As que lo que necesitamos es un conjunto de patrones relacionados. El grado en que los patrones
estn relacionados difiere. Algunas colecciones de patrones estn relacionadas de forma flexible y toman la forma
de un catlogo, mientras que otros estn ms fuertemente entrelazados. En este ltimo caso, hablamos de una

lenguaje de patrones .
6 Introduccin

experiencia en el dominio de varias disciplinas ha sido descrita con forma de patrn:

La idea de los patrones surgi originalmente de la arquitectura. El arquitecto Christopher


Alexander acu las frases 'Patrn' y 'patrn
idioma'. Se utiliza patrones para capturar la experiencia de un siglo en la construccin de ciudades y
casas (Alexander Ishikawa Silverstein 1977, Alexander, 1979).

La idea se hizo popular en la ingeniera de software a principios de 1990. El libro primer patrn de fi
ganar mucha atencin fue el libro sobre orientado a objetos
Patrones de diseo por Erich Gamma, Richard Helm, Ralph Johnson y John Vlissides - la 'banda
de los cuatro'. Este libro incluye un catlogo de modelos que describen diseos orientados a
objetos reutilizables (Gamma timn Johnson Vlissides 1995).

Desde mediados de 1990, una serie de libros de Patrn-Oriented Architecture Software ha cubierto
varios aspectos de la ingeniera de software. El primer volumen (Buschmann Meunier Rohnert
Sommerlad Stal 1996) se ocupa de la arquitectura de software en general, mientras que el segundo
(Schmidt Stal Rohnert Buschmann 2000) se centra en los sistemas distribuidos.

Jim Coplien ha trabajado intensamente en los patrones de organizacin. Su


Desarrollo generativo-Proceso lengua del patrn ( Coplien 1995) abarca la gestin de
organizaciones y proyectos, con nfasis en diversos aspectos del trabajo en equipo.

libro de Martin Fowler en Patrones de anlisis cubre anlisis de requisitos y modelado


analtico (Fowler 1996).

Software de memoria pequea por James Noble y Charles Weir ofrece las pautas de desarrollo de
software en un contexto en el que los recursos de memoria son limitados, tales como sistemas
embebidos (Noble Weir 2000).

Matrices de componentes de servidor Markus Vlter, Alexander Schmid y Eberhard Wolff presenta las
pautas de la construccin de infraestructuras de componentes del lado del servidor (Vlter Schmid Wolff
2002).

El libro de Alistair Cockburn en Sobrevivir a proyectos orientados a objetos da cuenta la experiencia de


los proyectos orientados a objetos e incluye un conjunto de patrones de gestin de proyectos
(Cockburn 1998).

Mary Lynn Manns y Linda Rising plan para publicar un libro de patrones de
La introduccin de nuevas ideas en las Organizaciones ( Manns Rising 2003).
Introduccin 7

Ms patrones se han creado para describir diversos aspectos de la ingeniera de software,


incluyendo el anlisis, la arquitectura y el diseo, la gestin y la enseanza. Muchos han sido
publicados a travs de los libros de la serie patrones (PLoPD 1995, 1996, 1998, 2000) oa
travs de las actas de la conferencia de EuroPLoP, la conferencia europea sobre patrones de
software (EuroPLoP 1998, 1999, 2000, 2001).

Linda Rising public una patrn Almanaque que consiste en un ndice de patrones en las reas de
software y relacionados, y que proporciona una rica lista de referencias (Rising 2000b).

Ms recursos sobre los patrones estn disponibles a travs del sitio web del Grupo de Hillside ( www.hillside.net),
un t fi organizacin sin nimo de lucro que se ejecuta varias conferencias patrones.

Los patrones no son inventados - que son observados. El gran beneficio de los patrones es que surgen de
la experiencia a largo plazo de muchas personas: los patrones representan el conocimiento madura.
Describen lo que ha funcionado en muchas ocasiones, que, por otro lado, significa que lo hacen no describir
la Ciencia resultados flamantes c. Los patrones en este libro han sido 'minada' durante muchos aos a
partir de varios proyectos en los que particip. Ellos describen la esencia de lo que ha funcionado bien en la
documentacin producida en estos proyectos. Los patrones no se detienen aqu. La comunidad patrones
pone mucho nfasis en la revisin de la cultura. La comunidad se ejecuta varias conferencias en las que se
escriben los patrones, ledo y discutido. Los autores reciben retroalimentacin sobre los patrones
presentados a travs de un proceso llamado 'pastoreo' antes de la conferencia. En la conferencia, los
patrones se someten a un proceso de revisin de sonido cuando son llevados a un taller de escritores. 2 Muchas
personas ofrecieron comentarios y compartieron su visin cuando las versiones anteriores de los patrones
en este libro se analizan en este tipo de talleres (Ruping 1998a, 1998b, 1999a, 1999b). Por lo tanto, este
libro contiene la experiencia compartida de muchas personas.

Muchos de los patrones en este libro le puede dar un 'aj!' experiencia, porque describen las cosas
con las que est familiarizado. La coleccin en su conjunto, sin embargo, es nuevo, y debe servir
bien como una gua compacta.

2. Esta cultura opinin ha sido descrita en varias obras: el libro de Richard Gabriel en talleres de escritura (Gabriel, 2002), as
como los lenguajes de patrones sobre el pastoreo por Neil Harrison (Harrison
2000) y sobre talleres de escritura de Jim Coplien (Coplien 2000).
8 Introduccin

Problema

Problema

Efectivo

discusin

Efectivo
Problema
Solucin

Efectivo

discusin
discusin Problema

Solucin Efectivo

Solucin
discusin

Solucin

Figura 2. Patrones - directrices en forma estructurada

estructura de Un gran beneficio de los patrones es que siguen una forma comn, estructurado, que los hace fcilmente

patrn accesible - una forma de patrn. La literatura patrn ha visto muchas formas diferentes, que van desde mayor
medida estructural para ms formas de prosa similar.
Introduccin 9

A lo largo de este libro, utilizo la forma patrn ilustrado en la Figura 2:

Cada patrn se inicia con una breve descripcin del problema. Esta declaracin consta de una
pregunta que se introduce en el problema.

Lo siguiente es la seccin de las fuerzas que motiva por qu el problema es realmente un problema.
La seccin describe que las fuerzas tienen una influencia sobre las posibles soluciones. A menudo
conflictivas fuerzas tirn en posibles soluciones y crear una tensin que la solucin va a resolver.

La solucin da una respuesta a la pregunta planteada en la seccin de problemas. Comienza


con una breve exposicin de cmo el problema puede ser resuelto, y contina con una
descripcin ms detallada de esa pauta.

Por ltimo, la seccin de discusin le da alguna informacin adicional y describe las relaciones
con otros patrones - en su mayora otros patrones en este libro, aunque de vez en cuando hay
conexiones a los patrones escritos por otras personas. 3

En conjunto, la seccin de problemas y el primer prrafo de la solucin fi forman una imagen en miniatura
que hace posible que usted pueda obtener una idea del patrn rpidamente. La seccin de las fuerzas, el
resto de la solucin y la seccin de discusin ofrecen ms detalles, informacin de fondo, y razn de ser.

3. Los nombres de patrn de patrones en el libro se ubican en pequeas capitales, mientras que los patrones escritos por otras personas estn en cursiva y
tener una referencia a la fuente original.
antecedentes del proyecto

Antes de sumergirse en las pautas actuales, me gustara tomar un breve vistazo a los proyectos de los que se
extraen los patrones en este libro. Es ms bien un conjunto diverso de proyectos, que van desde el desarrollo de
software a la consultora, a partir de la tecnologa antigua a la nueva tecnologa, desde pequeos equipos a los
equipos grandes. Yo estaba involucrado en la mayora de estos proyectos como un ingeniero de software, gerente o
consultor del proyecto, mientras que para algunos proyectos que tuviera la oportunidad de actuar como revisor. Estos
proyectos se llevaron a cabo en las organizaciones para las que trabaj durante los ltimos doce aos:

FZI (Forschungszentrum Informatik; Centro de Investigacin de Tecnologa de la Informacin), Karlsruhe,


Alemania, lleva a cabo proyectos de investigacin, as como colaboraciones industriales, con una buena
documentacin es una parte natural de todos los proyectos.

SD y software de diseo y gestin m AG, Alemania, es una compaa de software que maneja
proyectos en diferentes dominios de aplicacin - proyectos de desarrollo utilizando todo tipo de
tecnologa, as como proyectos de consultora. Documentacin juega un papel importante en la sd &
m, con un enfoque en la calidad ms que la cantidad.

Los ejemplos que ofrezco en este libro se basan en estos proyectos del mundo real. Los materiales de
ejemplo no son tomadas textualmente de estos proyectos, sin embargo, y no representan el contenido
original. Esto era necesario para evitar la divulgacin de informacin privada, como las ideas de
negocio y arquitecturas de software de propiedad de los clientes. Tambin tuve que traducir algo del
material original del alemn al Ingls. Adems, presento los proyectos de forma annima para evitar
Discom fi ting cualquier organizacin. Los temas, la estructura y los efectos de ejemplo, los
documentos son, sin embargo, la autntica.
12 antecedentes del proyecto

proyecto
Paracelso Cliente Una empresa alemana de software de tamao mediano

Tipo Desarrollo de software

Tema elementos de construccin de un marco para la gestin de


almacenes que el cliente pensaba vender a la industria farmacutica.

Bases Tcnicas UNIX, C ++

tamao 6 personas ms 2 personas de personal del cliente

Duracin 1 ao

Este proyecto eligi una especificacin preparada por el cliente que detalla las interfaces de los
componentes del marco deban ponerla en prctica. La primera tarea para el equipo del proyecto
para llegar a un diseo, que luego fue discutido con el cliente.

En la siguiente etapa, los componentes se implementan y se integran en el marco del cliente. Una
vez hecho esto con xito, el proyecto se consider completa. Ms tarde, el cliente hizo algunos
cambios en los componentes cuando se utiliz el marco, de los que ahora eran una parte, en
aplicaciones farmacuticas reales.

proyecto

Webber Cliente Una asociacin cientfica

Tipo Consultante

Tema La introduccin de la tecnologa Web para el cliente, creacin de un servidor


Web y estructurar el sitio Web.

Bases Tcnicas UNIX, Netscape Server, HTML

tamao 3 personas

Duracin 6 meses

Este proyecto se llev a cabo cuando la Web era todava nuevo - a principios de la dcada de 1990. El
cliente solicit el apoyo para la creacin de su nuevo sitio Web. El equipo del proyecto y el cliente se
reunieron para una pequea sesin de trabajo, en
antecedentes del proyecto 13

que se discutieron los contenidos y la estructura del sitio Web. Esto puso de manifiesto que el sitio
Web se supona que era un reflejo de la estructura jerrquica de la organizacin del cliente. El equipo
de re define la estructura del sitio web, un servidor web instalado y puesto en marcha el sitio.

Despus de que se complete el proyecto, el cliente desarroll el sitio Web ms all y mantiene el
servidor Web a s mismos.

proyecto

extricate Cliente Una compaa de seguros alemana de tamao mediano

Tipo Reingeniera

Tema Extraer informacin modificable sobre los productos de seguros desde el


sistema de gestin de la poltica en una base de datos.

Bases Tcnicas BS 2000, Windows NT, Cobol

tamao 8 personas ms 4 miembros del personal del cliente; ms personas


del cliente involucrado temporalmente

Duracin 2 aos

El objetivo de este proyecto fue redisear un sistema de seguro de vida legado de mejorar su capacidad de
mantenimiento. Esto implic una transformacin del modelo de datos, y una estrategia de migracin para
mover el sistema desde el modelo antiguo al nuevo. No se supona que la funcionalidad de cambiar.

Antes de iniciar cualquier actividad de migracin, el equipo tena que entender cmo funciona el sistema
antiguo. El equipo aprendi de los usuarios y documentado lo que haban entendido. Sobre la base de este
entendimiento, el equipo esboz el nuevo modelo de datos y describe la forma en que el sistema debe
funcionar en el futuro. La refactorizacin real a continuacin, se llev a cabo, la extraccin de muchas de las
propiedades no modificables en una base de datos.
14 antecedentes del proyecto

proyecto

persistor Cliente Una gran compaa de seguros alemana

Tipo Desarrollo de software

Tema La construccin de un marco para el acceso de base de datos, incluyendo versiones


objeto de la aplicacin; la introduccin del marco en varios proyectos.

Bases Tcnicas BS 2000, CICS, DB2, Windows NT, Cobol, un Cobol OO


extensin

tamao 6 personas, adems de 2 personas de personal del cliente; cerca de 50


personas de otros 6 proyectos durante el anlisis y la integracin de los
requisitos

Duracin 2 aos; integracin con otros proyectos que se extiende sobre ms de 2 aos

Este proyecto se inserta en el contexto ms amplio de otros proyectos relacionados que juntos desarrollaron
varios sistemas nuevos para una compaa de seguros. El objetivo de este proyecto especfico era proporcionar
una capa de acceso a la base de datos para ser utilizado en varias aplicaciones que fueron desarrolladas por los
otros proyectos. La capa de acceso de datos fue diseado como un marco, por lo que se podra adaptar
individualmente por los proyectos que la utilizaran.

El equipo del proyecto ha colaborado estrechamente con los equipos que trabajaron en los proyectos
relacionados, en particular durante la fase de especi fi cacin y la integracin de la capa de acceso a datos
en las aplicaciones.

proyecto

Vista Cliente Una gran compaa de seguros europea

Tipo Consultante

Tema Anlisis del panorama de aplicacin en la empresa del cliente y las


relaciones entre los diversos sistemas de software; gestin de riesgos.
antecedentes del proyecto 15

Bases Tcnicas Varios sistemas, COBOL, C ++, Smalltalk

tamao 2 personas; varios miembros del personal del cliente

Duracin 8 meses

la organizacin del cliente opera un gran nmero de sistemas que implementan muchos procesos de
negocio, utilizando una amplia gama de tecnologas. Algunos de los sistemas eran bastante nuevo,
mientras que otros haban estado en uso desde hace casi veinte aos. Todos estos sistemas trabajaron
juntos, pasar los datos entre s, llamar a las funciones y as sucesivamente. La comprensin de las
relaciones entre estos sistemas era importante por lo que el mantenimiento de toda la infraestructura de
sistemas se refiere.

El objetivo de este proyecto fue analizar el entorno de las aplicaciones y sealar los riesgos en la
arquitectura general.

Navegador de

proyectos Cliente Un proveedor de software de automocin

Tipo Desarrollo de software

Tema La construccin de una interfaz grfica de usuario para un sistema de navegacin y


comunicacin del automvil.

Bases Tcnicas Windows CE; C ++

tamao 8 personas

Duracin 1 ao

Este proyecto desarrollado varios componentes de interfaz de usuario para el que la especificacin fue
provista por el cliente. Los componentes se integran para formar una interfaz grfica de usuario completa tal
como se utiliza en los sistemas de navegacin y comunicacin que se encuentran en muchos coches.

El equipo diseado y codificado los componentes, asegurando que podra ser con fi gurada para que
coincida con diferentes 'apariencia' normas. Los componentes fueron probados bajo condiciones especfico
para sistemas embebidos.
diecisis antecedentes del proyecto

proyecto

Flexicar Cliente Un fabricante de automviles

Tipo Desarrollo de software

Tema Calendario de las etapas de produccin automatizadas para el tiempo y la minimizacin de

costos.

Bases Tcnicas UNIX, Java, aplicacin WebLogic Server

tamao 50 personas, entre ellos varios miembros del personal del cliente

Duracin 2 aos

Cuando se inici el proyecto, el cliente ya tena una idea clara de los resultados esperados del
proyecto. La fabricacin de automviles se compone de muchas etapas de produccin: el cliente
buscaba una programacin automatizada de estos pasos, de manera que las mquinas de produccin
se utilizaran para la capacidad mxima, y por lo tanto todo el proceso de produccin se volveran ms
rpido y por lo tanto menos costoso.

Los detalles de programacin eran claras a los expertos, pero la implementacin tcnica
representaron un gran reto. El equipo colabor estrechamente con el cliente en una precisa
especificacin, y dise el sistema de cuidado, teniendo en cuenta aspectos tales como los
requisitos de rendimiento y seguridad contra fallos. Una vez completada la aplicacin, el cliente lleva
a cabo el mantenimiento del sistema.

proyecto
AirView Cliente Una compaa area europea

Tipo Desarrollo de software

Tema Interfaz de usuario para facturacin de pasajeros.

Bases Tcnicas Ventanas, C ++, Java, CORBA

tamao 30 personas; varios miembros del personal del cliente tambin participan

Duracin 2 aos
antecedentes del proyecto 17

El esquema de este proyecto era proporcionar una nueva interfaz grfica de usuario para una
aplicacin de facturacin de pasajeros. La funcionalidad en s no sera cambiado. La interfaz de
usuario tena que cumplir con ciertos criterios ergonmicos. El proyecto comenz con un anlisis,
llevado a cabo con el cliente, de los casos de uso tpicos. Posteriormente, el equipo diseado algunos
elementos de la interfaz de usuario prototpicos y los discute con el cliente. Una vez hubo un acuerdo
sobre el aspecto detallado de la interfaz, los componentes se aplicaron plenamente.

proyecto

Contentis Cliente La organizacin paraguas de una industria alemana

Tipo Consultante

Tema La seleccin de un sistema de gestin de contenido web.

Bases Tcnicas UNIX, XML, HTML

tamao 3 personas, ms 2 miembros del personal del cliente

Duracin 3 meses

La organizacin del cliente buscaba un sistema de gestin de contenido web. El objetivo del
proyecto era apoyar a la organizacin con la eleccin de un sistema que encajar sus necesidades.
primera tarea del equipo fue analizar cules eran estas necesidades. El equipo habl con las
personas que iban a utilizar el sistema para determinar los procesos asociados con el
mantenimiento de los sitios web de intranet y extranet de la organizacin.

Un catlogo de criterios emergi del anlisis de procesos que el sistema de gestin de contenidos
tuvo que ful fi l. Una vez que se estableci la lista completa de los criterios, se invit a varios
proveedores para demostrar sus sistemas en los talleres. Sobre la base de estos talleres, el equipo
hizo una recomendacin del sistema que cumpla con los requisitos del cliente mejor.

Proyecto

Puertas abiertas Cliente Una empresa en la industria fi nanciera

Tipo Desarrollo de software

Tema Diseo e implementacin de una arquitectura Web.


18 antecedentes del proyecto

Bases Tcnicas J2EE, JSP, Servlets, EJB, servicios web

tamao 50 personas, entre ellos varios miembros del personal del cliente

Duracin 2 aos

El cliente intencin de crear una arquitectura de software basada en Internet que les permiti llevar a
cabo el comercio electrnico a travs de Internet. El objetivo del proyecto fue la creacin de un portal a
travs del cual los bancos pueden acceder a informacin sobre los productos de seguros y vender estos
productos a sus clientes. El proyecto consista en varios equipos que colaboran. Un equipo trabaj en la
arquitectura general, un equipo trabaj en el contenido Web que se va a presentar, y ms equipos
trabaj en las aplicaciones individuales que iban a ser integrados en el portal. Un especial nfasis se
puso en la extensibilidad, por lo que el cliente podra integrar gradualmente ms aplicaciones como su
negocio exigi. Los equipos trabajaron en estrecha colaboracin para crear un primer prototipo de
trabajo del portal, a continuacin, extender el portal y que sea ms ampliamente disponible para los
socios de negocios.
1 Encontrar los temas correctos

La cantidad correcta de la documentacin es exactamente la necesaria para el receptor para hacer su siguiente
movimiento en el juego.

Alistair Cockburn (Cockburn 2001)

Hace un par de aos, un colega mo se uni a un proyecto que haba estado funcionando durante un
tiempo. En su primer da, se reuni con el director del proyecto, que ha explicado algunas cosas, luego le
entreg el nuevo miembro del equipo de un conjunto de documentos. Algunos de ellos eran enormes -
que contenan toda la especificacin de una aplicacin compleja. El director del proyecto estaba
visiblemente orgulloso del hecho de que su equipo haba producido tal documentacin completa. Un par
de horas ms tarde, vi a mi colega sentado en su despacho, delante de una gran pila de papel, mirando
bastante infeliz. Una pregunta acerca de cmo le iba con los materiales del proyecto revel que el pobre
hombre no estaba recibiendo el bien a todos. Dijo que estaba ahogando en la especi fi cacin, y que no
poda mantener a todos los detalles en su mente. Con el tiempo aprendi muchos de esos detalles, pero
ms de las discusiones con los otros miembros del equipo en las prximas semanas que la lectura de la
documentacin.

Recuerdo historias contrarias, as. Un colega, que acababa de unirse a la empresa, se le dio un
documento introductorio por su proyecto primero - un documento 20page que inclua todas las
cosas tiles que debe saber sobre el proyecto, as como una lista de personas de contacto de
diversas cuestiones. El colega coment ms adelante que este documento era muy til para hacer
su familiar con el proyecto.

En el primer incidente, la cantidad de informacin era simplemente demasiado grande. El nuevo miembro del
equipo recurri a cara-a-cara de la comunicacin, que es lo que el
20 Encontrar los temas correctos

director del proyecto debera haber previsto en el primer lugar. En el segundo incidente, la
brevedad del documento introductorio y los enlaces que se estuvieron la clave de su xito.

Alegando que los documentos ms cortos general, debe darse preferencia a los documentos ms largos es un
poco demasiado simplista, sin embargo. Recuerdo un equipo que tuvo que hacer un poco de refactorizacin y
estaban felices de que un documento de diseo sustancial estaba disponible, ya que los diseadores
originales ya no estaban en el proyecto. Este documento fue bastante detallado, ya que inclua un anlisis de
las alternativas de diseo que los diseadores originales haban considerado, y describe las razones para el
diseo que haban escogido. El documento fue de mucha ayuda durante la refactorizacin, y evit que el
equipo de la exploracin de opciones de diseo de los diseadores originales ya haban rechazado por buenas
razones.

Estas historias evocan la cuestin de por qu algunos documentos resultan ser tiles, mientras que
otros no lo hacen. Al parecer, algunas cosas pueden ser comunicados a travs de documentos muy
bien, pero otros no pueden. Con este fin, es til contrastar el papel de la documentacin con la
comunicacin cara a cara. La siguiente tabla resume las caractersticas importantes de cada uno.

Comunicacin cara a cara Documentacin

La interaccin directa ritmo determinado auto-Diferentes personas a


entender la informacin a diferentes velocidades.
La comunicacin cara a cara permite ciclos de
Muchas personas hallar todava tienen preguntas
preguntas y respuestas rpidas. Le preguntas algo,
alguien contesta, usted pide de nuevo en un detalle cuando una discusin ha terminado - preguntas

especfico, se obtiene una respuesta ms precisa, que no piensan en el calor del debate.

otra persona ofrece sus ideas y as sucesivamente. Documentos, sin embargo, permiten a la gente a

Cara a cara la comunicacin involucra a las personas leer a su propio ritmo, que van y vienen a travs del
de una manera muy directa. material, ya que necesitan.
21

Comunicacin cara a cara Documentacin

La comunicacin no verbal Las personas no se la comunicacin introvertido Mientras que algunas


comunican a travs de palabras exclusivamente. personas les gusta participar en el debate, otros no lo
Una gran parte de la comunicacin se lleva a cabo hacen. las personas introvertidas son a veces
de una manera no verbal - a travs del sonido, los dolorosamente en silencio durante las discusiones,
gestos y el lenguaje corporal subconsciente. Estas aunque pueden tener mucho que decir. Ellos tienen la
cosas son posibles slo a travs de la comunicacin palabra ms fcilmente cuando se les da la
cara a cara. oportunidad de escribir las cosas, ya que esto les
permite tener dudas y tomar tiempo para reflexionar.

Implicacin personal escalabilidad

Hablar el uno al otro significa llegar a conocer unos a Los documentos pueden estar ampliamente
otros. La creacin de confianza pasa mucho ms rpido disponibles. Puede hacer frente a un nmero casi
entre las personas que estn en la misma habitacin ilimitado de personas a la vez. Por otra parte, los
que entre las personas que se comunican a travs de la documentos pueden llegar a los miembros de un
escritura solamente. equipo distribuido - personas que trabajan en diferentes
lugares.

rpida disponibilidad disponibilidad a largo plazo Una vez que un proyecto

llegue a su final el equipo se dispersa - expertos ya no


En un proyecto bien organizado, hay Expertos al
pueden estar disponibles. El software, sin embargo,
alcance del odo ( Cockburn
1998) fcilmente disponible para responder a las todava se necesitan un mantenimiento o incluso

preguntas que pueda tener. Las discusiones pueden refactorizacin. Tan slo aquellos documentos escritos

llegar en el calor del momento. Los documentos pueden estn disponibles ms all de los lmites del proyecto real.

estar disponibles tambin, pero pasa el tiempo hasta


que los documentos estn escritos y puestos a
disposicin.
22 Encontrar los temas correctos

Por lo tanto cara a cara la comunicacin y la documentacin no se oponen entre s. Tampoco es


generalmente mejor o ms eficaz que el otro. Qu canal de comunicacin es ms apropiado siempre
depende de la situacin. O bien tiene sus ventajas, y ambos se complementan entre s. Hay un
montn de ejemplos de la vida cotidiana. Los estudiantes aprenden de los libros, as como de las
lecciones de sus maestros. Aprendemos lo que est pasando en el mundo que nos ambos a partir de
la lectura del peridico y de hablar con nuestros amigos. Ni tampoco la comunicacin verbal ni escrita
es prescindible en una sociedad civilizada. No es de extraar, por tanto, que los proyectos requieren
tanto la comunicacin cara a cara y documentacin escrita. Intercambio de informacin ocurre con
frecuencia en los proyectos de software, y sucede en contextos muy diferentes. documentacin gil
pretende utilizar el tipo de comunicacin que mejor se fi cios tales contextos.

As contextos en los que se escribe la documentacin recomendada? Volvamos al manifiesto gil por
un momento. El manifiesto dice que los individuos y la interaccin, as como el software de trabajo, son
algunos de los valores fundamentales de un proyecto de desarrollo gil. Podemos concluir que la
documentacin es ms valioso si contribuye a estos objetivos generales. En este sentido, la
documentacin es un medio, no un fin. Cuanto ms ayuda a los individuos interactan en un equipo, la
documentacin se vuelve ms til y ms fcil se hace para el equipo de desarrollo de software que
trabaja.

Esto al menos es cierto para los proyectos de desarrollo. En los proyectos de consultora, sin embargo,
la documentacin puede ser el objetivo principal. Aunque los proyectos de desarrollo no estn fuera del
alcance del manifiesto gil, podemos aplicar una actitud gil a los documentos escritos en proyectos de
consultora tambin. Este libro no promete un fl integracin global super mtodo de documentacin.
Proyectos difieren en gran medida y los requisitos de documentacin difieren de un proyecto a otro. Por
lo tanto, este captulo no presentar una lista de documentos y le dir que estos son los documentos que
necesita su proyecto. En su lugar, he elaborado varios modelos que le guan en su camino para de fi nir
los requisitos de documentacin espec fi co para su proyecto individual, y la determinacin de los
contenidos necesarios de dichos documentos.

La Figura 3 presenta un diagrama de hoja de ruta de estos patrones. Se esboza los patrones y las
relaciones que existen entre ellos, y por lo tanto le da un breve resumen de este captulo.
23

apreciar la SEPARACIN DE
OBJETIVO LECTORES DESCRIPCIN Y
EVALUACIN
La informacin

apreciar centrada facilita

pregunta por

apreciar

REQUISITOS DE
Centrarse en la pertinencia
DOCUMENTACIN
mantener una LARGO PLAZO
INDIVIDUALES

Puede elegir
EL GRAN IMAGEN
entre las
mantiene una

aprende est en
PORTAFOLIO
de sincrona con el

usos ESFUERZO CONJUNTO

sugiere una
sugiere para
DOCUMENTACIN documentar la

servir como entrada

para el ESPECIFICACIONES COMO

FUNDAMENTOS
ejemplos
DE DISEO
reales
ayudar a explicar la

Figura 3. Patrones de hallazgo de los temas correctos


24 Encontrar los temas correctos

Los lectores de destino

Problema Cmo puede el equipo de proyecto asegurar que los documentos que producen ser apreciado?

Efectivo La documentacin del proyecto se dirige a muchos lectores diferentes: gerentes de proyecto, arquitectos,
diseadores, programadores y usuarios. La gente en diferentes roles suelen tener diferentes perspectivas, y
estn interesados en diferentes aspectos de un proyecto de software. Los gerentes podran no estar
interesados en la lectura de un documento ms tcnico, incluso si son capaces de entender que, mientras que
los programadores podran no estar interesados en un resumen de gestin.

Por otra parte, diferentes personas a menudo tienen diferentes orgenes. El material puede ser sencillo para

algunas personas y culto fi cultad para entender a los dems. Pero son los lectores para los cuales se prepara

un documento de proyecto (Haramundanis


1998). Si el documento no se adapta a las necesidades de los lectores previstos, es probable que sea de poco o ningn
uso.

Peor an, la propia existencia de un documento es cuestionable si no est claro quin debe leerlo.
Si la audiencia no puede ser nombrado, cul es el punto en la redaccin del documento?

Solucin En primer lugar, cada documento debe tener un pblico objetivo, y debe hacer frente a estos
lectores con el fin de ser til.

En un contexto gil, no se escribe un documento debido a un proceso dicta. Se escribe un


documento, ya que los documentos ls fi ful un propsito para los lectores previstos.

Por ello, el primer paso es decidir, para cada documento, que son los lectores de destino. Estos pueden ser
compaeros de un mismo proyecto, actuando en cualquiera de las funciones mencionadas anteriormente, los
colegas de otros proyectos futuros, tal vez los miembros del equipo, tal vez los clientes.

Una vez que esto est claro, que coincide con el documento a las necesidades de los lectores incluye lo siguiente:

Dejando claro que los lectores de destino son al mencionarlos explcitamente, preferiblemente cerca de la parte
delantera.

Explicando qu informacin de fondo es necesaria para la comprensin del documento. Esto puede
ser el conocimiento tcnico o conocimiento del proyecto especfico cs.
Los lectores de destino 25

No asumir ms conocimiento de fondo que se puede esperar entre los lectores de destino.

Restringir el alcance del documento a lo que los lectores de destino esperarn. Esto ayuda a
mantener la documentacin corto y preciso, al igual que la restriccin del nivel de detalle de lo
que los lectores puedan entender destinados.

Haciendo que el documento de lectura, proporcionando ejemplos y otro material complementario


de la vida cotidiana del proyecto de sus lectores. Cuando se prepara un documento, considerar su
trabajo como un servicio a los lectores, y por lo tanto siguen preguntando: 'Qu informacin
necesitan mis lectores' 'Quin son mis lectores de destino', y 'Cmo sern mis lectores ser capaz
de entender?

Si la conclusin de que no se puede determinar que los lectores de destino son y por qu deben
leer el documento, hay una alta probabilidad de que el documento es innecesario.

Discusin Varios otros patrones ayudan a implementar este patrn. Dirigindose a los lectores de destino tiene
mucho que ver con el mantenimiento de un foco: cuanto ms se centr el documento es, ms claro que
puede hacer que el pblico objetivo. Presentacin La informacin centrada le ayuda a permanecer en blanco. La
inclusin de ejemplos reales y de un GLOSARIO hace que sea ms fcil para sus lectores a entender lo que est
diciendo.

Ciertos documentos de encontrar un gran nmero de lectores con facilidad. Por ejemplo, los documentos de informacin
general entran en esta categora - documentos que describen EL PANORAMA
de una arquitectura de software. Debido a que tales documentos tienen muchos lectores de destino, que son
tiles en muchos proyectos.

La toma de conciencia de los lectores de destino es una cosa, dirigindose a ellos directamente es otra.
los DIRECTRICES PARA LOS LECTORES al principio de un documento es el lugar perfecto para explicar quines
son los lectores de destino y la informacin de fondo es necesario para la comprensin del documento. A
veces es difcil imaginar lo que los lectores de material se puede esperar de un documento, y lo que los
lectores sern o no ser capaz de entender. Si encontramos esto hace que sea difcil de definir el alcance
del documento, se puede pedir a los dems para revisar el esquema del documento. Alguien desde fuera
del proyecto tal vez puede tomar Una vista distante y proporcionar retroalimentacin.
26 Encontrar los temas correctos

La informacin centrada
Problema Cmo se pueden prevenir los documentos de meandros y llegar a ninguna parte?

Efectivo La documentacin del proyecto en su conjunto a menudo aborda mltiples temas y se distribuye
normalmente durante varios documentos. Esto invita a las siguientes preguntas: en qu casos debe optar
por documentos separados, qu material debe ir en cada documento, y cunto tiempo deben ser los
documentos individuales? El primer aspecto fi vale la pena mencionar es que los documentos relativamente
cortos y concisos ayudan a mantener la documentacin del proyecto en mrgenes razonables. Esto es
deseable tanto para el equipo de proyecto que tiene que gastar recursos en la documentacin, y para los
lectores que deben tener acceso a informacin de forma rpida y fiable.

Sin embargo, la brevedad solamente no hace documentos fcil de usar. Otro aspecto importante es evitar
la informacin redundante. Si deja que cada documento cubre exactamente un tema, puede evitar
solapamientos entre los documentos en gran medida. Esto tiene dos ventajas. En primer lugar, un claro
foco en un tema hace que sea fcil para los lectores para identificar el documento que contiene la
informacin que estn buscando. En segundo lugar, evitar la informacin redundante hace que los
documentos ms fciles de mantener y evita que se convierta en la documentacin inconsistente. Evitar la
informacin redundante tambin tiene inconvenientes. Si, en un intento de evitar la redundancia, tambin
muchos aspectos se extraen en los documentos de su cuenta, los documentos resultantes sern menos
autnomo. Los documentos se repleta de referencias a otros documentos, lo cual es contrario a la intuicin
a la lectura secuencial normal.

Solucin A fi cables enfoque claro e identi sobre un tema en particular hace un documento conciso y
directo. El documento sencillo ofrece la informacin relevante a este tema, pero no ms que
eso.

Por lo tanto, la informacin relacionada debe entrar en un documento separado si puede ser considerado para

formar un tema de su propia, mientras que la informacin que es necesaria para la comprensin inmediata de un

documento debe mantenerse dentro de l. Aqu hay algunas seales que indican si un documento tiene un

enfoque claro:

Un documento debe ser apropiadamente titulado; un ttulo claro sugiere que el enfoque del documento tambin
est claro.
La informacin centrada 27

Las diferencias de alcance entre dos documentos relacionados deben ser claras de sus ttulos.

Un resumen o un resumen al principio de un documento pueden explicar el enfoque del


documento.

Todas las secciones del documento deben ser de un material que es relevante para el tema del
documento representa.

Puede lograr documentos sencillo si usted se recuerda para comprobar que todo lo que est
diciendo realmente contribuye al tema del documento representa. Si encontramos que este no es el
caso, volver atrs y preguntarse cul es el propsito del documento es, y lo que tiene la intencin
de transmitir a sus lectores.

La consecuencia de este patrn es que a evitar informacin redundante hasta cierto punto, pero no del todo.
Las pequeas coincidencias entre los documentos son definir la medida en que son necesarias para hacer
auto-contenida documentos. Este patrn no slo se aplica cuando se configura un nuevo documento.
Documentos evolucionan como un proyecto contina, y es importante que no evolucionan en una masa
detallado del texto, creciendo ms all de duracin razonable. Cada vez que aade informacin a la
documentacin del proyecto, asegrese de que la informacin entra en el lugar correcto, por lo que todos los
documentos del proyecto mantienen su enfoque.

Discusin UN CARTERA DE DOCUMENTACIN es un primer paso hacia la informacin centrada. Esta cartera se describen
diversos tipos de documentos que puede necesitar un proyecto, y cules son sus contenidos son tpicos.
La cartera tiene en cuenta que cada documento tiene un grupo distinto de A quin va destinado. Se puede
definir con precisin el foco de cualquier documento de la cartera, adaptndolo a las expectativas de sus
lectores previstos.

Los documentos que se crean en un proyecto forman la documento horizontal - una red de documentos
relacionados que los miembros del equipo utilizan para la comunicacin. El ms centrado los documentos
individuales son, ms clara ser la Documento horizontal, y como consecuencia, el ms eficaz es. informacin
sobre el tema no slo es deseable para los documentos completos, pero se puede analizar a nivel de
captulos y secciones de los documentos individuales. Esto es especialmente cierto para los documentos
que se presentan La informacin estructurada - un formato que emplea elementos estilsticos para transmitir la
estructura de un documento y su contenido.
28 Encontrar los temas correctos

Requisitos de documentacin individuales


Problema Cmo se pueden evitar los requisitos de documentacin innecesarios?

Efectivo Hay proyectos de desarrollo que puede hacer con muy poca documentacin. Los equipos pequeos
que trabajan en un sitio se pueden hacer a menudo sin la documentacin completa. Por ejemplo, XP
(eXtreme Programming) es bien conocida por producir slo un mnimo de documentacin (Beck, 2000).
Otros proyectos, sin embargo, requieren ms documentacin. Tal vez los interesados en el proyecto
piden ms documentacin, tal vez el equipo necesita los documentos para la comunicacin entre sitios,
quizs necesita el diseo que se describe con ms rigor que es posible usar slo una discusin
informal. La causa de los diferentes requisitos de documentacin se encuentra en parte en las diversas
metodologas que pueden seguir diferentes equipos, y en parte en el hecho de que los alcances del
proyecto difieren. Podemos construir un nuevo software o podemos redisear los sistemas existentes.
A veces diseamos la arquitectura general, a veces contribuimos componentes de un todo mayor. Un
proyecto puede implicar una sola persona o cientos de personas.

Por otra parte, los proyectos de desarrollo y proyectos de consultora pueden conectar diferentes
significacin a la documentacin. En los proyectos de desarrollo, el valor de la documentacin a menudo
puede ser medida por lo bien que la documentacin contribuye a la comunicacin dentro del equipo. En
los proyectos de consultora, sin embargo, la documentacin puede ser el objetivo del proyecto. En su
libro sobre Modelado gil, Scott Ambler escribe: 'Cada sistema tiene sus propias necesidades de
documentacin nica; un tamao no encaja todos', y recomienda: 'Que sea lo bastante simple, pero no
demasiado simple'(Ambler 2002). En una lnea similar, Alistair Cockburn, en su libro sobre Desarrollo gil
de Software, recomienda la creacin de documentacin que es 'la luz, pero su fi ciente' o 'apenas su fi
ciente', y contina: 'La cantidad ideal apenas su fi ciente, vara segn la hora y el lugar dentro de un
mismo proyecto.' (Cockburn 2001)

En otras palabras, si definimos un proceso de documentacin estndar para todos los proyectos, y la fuerza de los
equipos para crear todos los documentos que podran ser tiles en cualquier un contexto, se impone una carga de
trabajo de documentacin innecesaria en muchos proyectos.
Requisitos de documentacin individuales 29

Solucin El enfoque ms eficaz para la documentacin es para cada proyecto para definir sus requisitos
de documentacin de forma individual.

La cantidad real de documentacin necesaria depende de factores como el tamao del proyecto, si
el equipo puede trabajar en uno o sitio no, y criticidad del proyecto, entre otras cosas.

Puede romper la cantidad 'correcta' de la documentacin de su proyecto en lo siguiente:

La cantidad de documentacin requerida por los interesados en el proyecto.

La cantidad de documentacin que el equipo necesita para comunicarse.

La cantidad de miembros individuales del equipo de documentacin que tenga que pensar en ideas a
travs.

La cantidad de documentacin que el proyecto necesitar en una etapa posterior.

La cantidad de documentacin necesitar probablemente un proyecto de seguimiento. Los


requisitos de documentacin individuales deben de definir qu documentos son necesarios y qu
material deben cubrir estos documentos. documentacin gil le invita a hacer sin ningn tipo de
documentos que considere innecesario en una situacin concreta, pero, por otro lado, para planificar
activamente por los documentos que se necesitan.

requisitos de documentacin pueden cambiar con el tiempo. Ms documentacin puede ser


necesario, por ejemplo, hacia el final de un proyecto cuando el equipo pronto dispersarse. O menos
documentacin puede ser necesario, por ejemplo, durante las etapas de intensa colaboracin en el
que todos los involucrados puedan comunicarse fcilmente directamente. Re-evaluar los requisitos
de vez en cuando es necesario para mantener la documentacin en el nivel apropiado del volumen y
detalle.

Discusin Elaboracin de lo que la documentacin del equipo o necesitan los interesados en el proyecto
est estrechamente relacionada con la elaboracin de quin es el lectores de destino de documentos son
posibles. La tarea real de de fi nir los requisitos de documentacin debe ser parte de cualquier proyecto
gil. Si se piensa en la documentacin como Un DISTINCT ACTIVIDAD, se puede de fi nir los requisitos de
documentacin y los recursos va a pasar en la misma forma que planea cualquier otra actividad del
proyecto.

De fi nir los requisitos de documentacin de forma individual para cada proyecto no significa que
usted tiene para definir desde cero cada vez. UN DOCUMENTO-
30 Encontrar los temas correctos

ATION PORTAFOLIO puede mostrar lo que podran ser necesarios documentos y cules podran ser sus contenidos.
A continuacin, puede elegir los documentos que necesita y adaptarlos a necesidades especficas de su
proyecto.

Cartera documentacin
Problema Cmo pueden los equipos de reutilizar el conocimiento sobre la cual podran ser necesarios documentos en sus
proyectos?

Efectivo No hay ningn punto de la hora de definir un proceso de documentacin estndar o requisitos de
documentacin estndar para proyectos de software en general. proyectos de software son demasiado
diverso para los requisitos de la norma a ser posible. Muchos proyectos de software No obstante tienen
cosas en comn. Por ejemplo, casi todos los proyectos de software hacen una diferencia entre lo que un
sistema, un programa o un mdulo hace, por un lado, y cmo sus componentes internos estn diseados
por el otro. Esta distincin se debe a la 'ocultacin de informacin' principio (Parnas 1972) y que a menudo
se refleja en la documentacin, lo que resulta en documentos separados para el sistema espec fi cacin y
el diseo del sistema. Hay otras categoras de documentos que se encuentran en varias ocasiones en la
documentacin del proyecto, que van desde documentos en las pruebas a los documentos que explican
cmo utilizar el software. Muchos proyectos requieren documentos orientados a la gestin. A pesar de que
estos documentos varan mucho en longitud y detalle, no hay ninguna razn para que cada proyecto debe
reinventar las categoras de documentos que deben ser considerados cuando los requisitos de
documentacin son de fi nido.

Solucin Una cartera documentacin describe los documentos que podran ser necesarios en un proyecto
de software, y su alcance. Si una organizacin establece dicha cartera, los proyectos pueden
elegir aquellos documentos que necesitan, comprobando la necesidad de cada documento
individual candidato.

Una cartera de documentacin impide que el equipo de tener que decidir qu existen documentos
candidatos. La cartera incluye un conjunto de sugerencias para el equipo a tener en cuenta.

La Figura 4 presenta una cartera de documentacin que incluye los documentos candidatos para la mayora de
los proyectos de software. Una lista similar se da en el libro de Scott Ambler sobre Modelado gil en el captulo de
la documentacin (Ambler 2002). Usted puede
Cartera documentacin 31

utilizar esta cartera, o se puede adaptar a las necesidades tpicas de los proyectos de su organizacin.

Los documentos incluidos en el otoo cartera en las siguientes categoras:

administracin documentos definen el contexto de gestin para un proyecto, tales como el


alcance global y la programacin del proyecto. Un ejemplo tpico es el resumen de gestin - un
documento que describe los objetivos generales del proyecto y las pone en un contexto de
negocios. documentos de gestin tambin pueden incluir un breve documento que introduce
nuevos miembros del equipo para el proyecto.

Speci fi cacin documentos describen lo que hace el software. Esto incluye aspectos tan extendida
como datos, la funcionalidad, la interfaz de usuario, e fi ciencia y ms. El propsito principal de los
documentos fi caciones es aclarar exactamente lo que se necesita software. Espec fi cacin
documentos sirven como base para las discusiones con el cliente, o como base para la discusin con
los equipos que trabajan en tareas relacionadas. Adems, la especificacin es lo que un sistema
puede ser probado contra.

Diseo documentos explican cmo funciona el software, incluyendo por qu funciona de esta manera. Se
ven en el funcionamiento interno de un sistema, un mdulo o una clase, en su estructura y su
comportamiento. Pequeas solapamientos con la especificacin son posibles - el modelo de datos, por
ejemplo, es importante durante tanto espec fi cacin y diseo. Los documentos de diseo se utilizan
sobre todo para la comunicacin entre el equipo de desarrollo, sino que tambin pueden ser tiles para la
comunicacin con el cliente interesado. Un documento de diseo puede ayudar a pasar en la experiencia
del proyecto para futuros proyectos - un mecanismo de gestin del conocimiento que no debe ser
ignorado.

Casi ningn proyecto es una isla. A menudo hay un viejo sistema que va a ser reemplazado por el
nuevo software hasta cierto punto, tal vez poco a poco. Esto puede hacer una migracin concepto
necesario. Un concepto de migracin se describe cmo la funcionalidad del sistema anterior da
paso a la funcionalidad del nuevo sistema, y cmo los datos que hayan sido almacenados por el
sistema antiguo se transforma en datos que pueden ser utilizados por el nuevo sistema.
32 Encontrar los temas correctos

Gestin de proyectos

Resumen de gestin

Plan de entrega

Proyecto directrices Manual / equipo

Requisitos espec fi cacin Diseo

Resumen del sistema Introduccin a la arquitectura

Los casos de uso Modelo de datos

Modelo de datos jerarqua de clases

Funcional especificacin diagramas de interaccin Clase

Interfaz de usuario especfico de cationes diseo de la interfaz de usuario / gestin de


eventos
comportamiento sincronizado

de acceso a la base de datos / transacciones


requisitos no funcionales (velocidad de
ejecucin, mantenimiento, etc.) La integracin con los sistemas vecinos

Glosario
Directrices y convenciones de nomenclatura

Migracin Uso

la migracin funcionalidad Directrices de uso / conceptos

Migracin de datos Cookbook

Tutorial

Prueba operaciones

Los casos de uso despliegue

Casos de prueba pautas de las operaciones

prueba de concepto Solucin de problemas

Figura 4. Una cartera documentacin


Cartera documentacin 33

A menudo, las pruebas han de ser especi fi cado, tal vez usando prueba documentos. Estos pueden
solaparse con la especificacin. Los casos de uso, por ejemplo, caen en una u otra categora (Cockburn
2000). Dependiendo de las necesidades reales del proyecto y los clientes, un conjunto completo de casos
de prueba puede servir como el sistema espec fi cacin, y puede hacer que los documentos espec fi
cacin separados redundantes en algn grado.

Uso documentos describen cmo se pueden usar un sistema, mdulo o clase. Ellos describen el
uso de parmetros, por ejemplo, y el orden en que las funciones pueden verse, y con frecuencia
son necesarios para la integracin de sistemas. documentos de uso pueden llegar a ser no ms
de unas pocas directrices, pero pueden equivaler a un concepto global de uso. Al entregar un
marco, por ejemplo, el uso del concepto merece especial atencin, ya que aconseja a los usuarios
cmo crear una aplicacin de trabajo.

operaciones documentos describen cmo un sistema se va a operar y cmo se pueden abordar los problemas
relacionados con el funcionamiento.

Muchos de los documentos mencionados anteriormente son bien conocidos de la literatura sobre la
ingeniera de software (Sommerville, 1996) o de mtodos de ingeniera de software, como el Proceso
unificado (UP) (Jacobsen Booch Rumbaugh 1999, Kruchten 2000).

Su proyecto puede o no puede necesitar cualquiera de los documentos enumerados aqu, o tal vez se
puede combinar varios documentos de una categora en un solo documento. Tal vez algunos
documentos son completamente innecesarios en su situacin. Corresponde al equipo del proyecto
para decidir qu documentacin es necesaria en una situacin especfica, teniendo los requisitos del
cliente en cuenta. Una buena dosis de escepticismo est bien cuando se trata de la decisin sobre
qu documentos del proyecto deben ser escritos. desarrollo de software gil nos anima a proporcionar
la documentacin que es necesario, pero ir sin papeleo innecesario.

Discusin Se necesita la decisin sobre si es o no es un documento de la cartera est estrechamente


relacionado con que la lectores de destino son. Si no se puede nombrar el
OBJETIVO LECTORES para un documento, el proyecto probablemente puede prescindir de ese documento.
Despus de todo, qu conjunto de documentos que decida producir depende de la INDIVIDUAL REQUISITOS DE
DOCUMENTACIN de su proyecto. Un proyecto UP es probable que lleguen a conclusiones diferentes a las de un
proyecto XP. Los documentos de la cartera pueden variar en alcance y nivel de detalle. UN CONCENTRARSE EN A
LARGO PLAZO PERTINENCIA le ayuda a incluir informacin que es til en el
34 Encontrar los temas correctos

a largo plazo y para producir documentos con alta significacin. Por otro lado, la informacin que
pronto ser irrelevante probablemente no necesita ser documentada.

Visin general de documentos normalmente atraen el mayor nmero de lectores. resmenes de gestin, descripciones
generales de arquitectura y as sucesivamente describir EL PANORAMA
de un proyecto o un sistema. Para muchos proyectos, estos documentos se encuentran entre los ms
importantes dentro de la cartera.

documentos ms detallados, sin embargo, estn en el centro de la disyuntiva entre la comunicacin verbal y
escrita. Un documento fi especificacin, por ejemplo, es tpicamente el resultado de un anlisis de requisitos. Se
puede complementar las discusiones con el cliente, pero nunca puede sustituir a estas discusiones. (Ver tambin Especificacin
como un esfuerzo conjunto.) Casi todos los proyectos necesitan un documento especi fi cacin, pero no necesariamente
uno en el posible nivel de fi nido de detalle. Del mismo modo, la documentacin de diseo es necesario y til en la
mayora de los proyectos. En la mayora de los casos, sin embargo, los documentos de diseo no tiene por qu
estar preocupados con los detalles tcnicos de bajo nivel, que se comunican mejor cara a cara. Los documentos
de diseo en su lugar deberan centrarse en el FUNDAMENTOS DE DISEO - la motivacin que llev a las decisiones
de diseo que el equipo ha hecho.

Por ltimo, la clasi fi cacin dada por la cartera de documentacin contribuye al objetivo de presentar La
informacin centrada. Toscamente bocetos que documenta que pueda necesitar y describe cmo estos
documentos pueden centrarse en un tema en particular.

Centrarse en a largo plazo Relevancia

Problema Cmo pueden evitar la produccin de proyectos de documentacin que expira antes de tiempo?

Efectivo documentacin de los proyectos de software se ocupa de un conjunto ms diverso de informacin. La


informacin que se basan en los rangos de las especi fi caciones para el diseo, de los principios generales
a los detalles tcnicos, de equipo orientado a orientado al cliente. En un proyecto gil, que no documentan
de forma automtica toda esta informacin por escrito. Un proyecto gil evita gastar ms recursos en la
documentacin de lo necesario, y se concentra en aquellos documentos que tienen un propsito claro que
justi fi que el tiempo y el esfuerzo que entra en su produccin.
Centrarse en a largo plazo Relevancia 35

Por otra parte, si usted decidi preparar los documentos para cada aspecto del proyecto, puede
optar por la comunicacin escrita como medio de manera indiscriminada y sin tener en cuenta su
adecuacin.

Estos factores conducen a la pregunta: cmo se puede determinar si un documento escrito es


apropiado o no?

Vamos a echar un vistazo a un proyecto de software hecho de una manera gil. La gente intercambiar
ideas con frecuencia a travs de discusiones y la comunicacin informal. Mucha de la informacin que
se intercambia es importante en el impulso del momento, para ayudar a los miembros del equipo a
progresar con su trabajo actual. No toda esta informacin ser relevante un par de meses o aos ms
tarde. Algunos s, sin embargo. Ser gil no significa ser miope. La literatura sobre el desarrollo gil nos
recuerda que al tiempo que ofrece el software es el objetivo principal de un proyecto de desarrollo, la
preparacin para futuros proyectos es un objetivo secundario que no debe ser ignorado (Ambler 2002).
Esto es lo que significa Alistair Cockburn por 'preparacin para el prximo partido' (Cockburn 2001).
Para prepararse para una etapa posterior del proyecto, o para un proyecto futuro, hay que capturar el
conocimiento de que otros se basan en.

Este es el punto en el que la documentacin puede desplegar su mayor beneficio: el conocimiento que debe
ser preservada para el futuro es vale la pena documentar. Esto no es una mera suposicin. la preservacin
del conocimiento ha sido objeto de mucha discusin y mucha investigacin. Por ejemplo, Stuart Marca hace
hincapi en la importancia de las bibliotecas digitales y no digitales en su libro sobre el pensamiento y la
planificacin a largo plazo, El Reloj del largo ahora ( Marca 1999).

Solucin Hay mucho valor en la documentacin que se centra en cuestiones que tienen una importancia a largo plazo -
cuestiones que desempearn un papel en una fase posterior del proyecto o en proyectos futuros.

La documentacin es esencialmente un instrumento para la gestin del conocimiento, tanto dentro de un proyecto ya
travs de proyectos:

Documentos, cuando describen los fundamentos de un proyecto, son importantes en todas las
fases de los proyectos. Los ejemplos incluyen una especificacin esencial, o un documento
central que describe la arquitectura de software. La relevancia a largo plazo de estas cuestiones
sugiere que deben ser capturados en forma escrita.
36 Encontrar los temas correctos

Las lecciones aprendidas de un proyecto son a menudo tiles para futuros proyectos. Insight gan en
la arquitectura de software, las decisiones de diseo o conclusiones extradas en una retrospectiva
proyecto son todos los candidatos a la documentacin escrita.

Hay menos valor en la documentacin exhaustiva de las cosas slo guarden relacin a corto plazo.
Si, debido a los recursos limitados, no todo puede ser documentado - que es casi siempre el caso -
se debe dar preferencia a los temas a largo plazo con significacin.

Discusin Este patrn est estrechamente relacionado con el lectores de destino patrn. Ambos patrones plantean la
cuestin de si la produccin de un documento es justificado o no. El aumento de esta pregunta es esencial
cuando se elige los documentos que su proyecto necesita de la CARTERA DE DOCUMENTACIN. Existen varios
ejemplos de documentos que tpicamente se caracterizan por una relevancia a largo plazo y son casi
siempre justificado: un documento que describe EL PANORAMA, un documento especi fi cacin, siempre que
el equipo realiz la ESPECIFICACIONES como un esfuerzo conjunto

con el cliente, y un documento para la FUNDAMENTOS DE DISEO.

Si un tema tiene relevancia a largo plazo y debe ser documentado ms all de los lmites del proyecto
actual, la disponibilidad a largo plazo se convierte en un problema. Para tener la lectores de destino beneficio
del documento, debe ser ampliamente disponible. Esto es esencialmente una cuestin de gestin de la
documentacin, y se aborda en el INFORMACIN MERCADO y GESTIN DEL CONOCIMIENTO patrones.

Espec fi cacin como un esfuerzo conjunto

Problema Cmo pueden los proyectos de desarrollo de asegurar que se dirigen en la direccin que el cliente
quiere?

Efectivo La especi fi cacin de un sistema de software requiere una gran cantidad de las aportaciones de los expertos de
dominio. Una estrecha colaboracin entre los expertos en software y los expertos de dominio es necesario
asegurarse de que el software cumple con las expectativas del cliente. El equipo del proyecto debe aprender de los
expertos en el dominio lo que se supone que el software para hacer. Esta colaboracin implica una gran cantidad
de la comunicacin cara a cara.

Sin embargo, es peligroso confiar en la comunicacin verbal sola, por dos razones. En primer
lugar, no puede haber malentendido entre el equipo del proyecto y el cliente que no revelar
incluso una serie de debates a fondo. A menudo,
Espec fi cacin como un esfuerzo conjunto 37

usted puede pensar que ha llegado a un entendimiento comn durante una discusin, pero cuando intenta
confirmar su comprensin sobre el papel, que hallar este no es el caso. Una especificacin escrita es mucho
menos propensos a dejar que los malos entendidos pasan desapercibidos.

En segundo lugar, un documento escrito puede evitar disputas sobre quin tiene razn y quin est
equivocado, debera diferentes surgen opiniones sobre los requisitos del sistema, quizs varios meses de
iniciado el proyecto. Incluso la relacin ms amigable al cliente sufre cuando se hacen acusaciones de que el
equipo dise el software equivocado. Una especificacin escrita evita en gran medida tales acusaciones.
Esto es an ms cierto cuando se trata de ms de dos partes. Esto no es raro - a menudo varias compaas
de software colaborar en un proyecto, y los diferentes departamentos de la organizacin del cliente tambin
pueden tener una participacin en el proyecto. En tal proyecto una especificacin escrita da a todas las
partes cierta seguridad de planificacin.

Esto no significa que el sistema tiene que ser especi fi cado hasta el detalle fi nido, ni significa que
los requisitos no pueden sufrir cambios. Es aceptable dejar detalles abierto en la especificacin,
pero la especificacin debe dejar esto en claro, por lo que el equipo es consciente de las
decisiones que an se tienen que hacer.

Cambiantes requisitos se consideran natural en un proyecto gil que sigue un proceso de desarrollo
iterativo. El documento especi fi cacin ayuda a hacer frente a los requisitos cambiantes de una manera
aceptable, la actualizacin del plan de proyecto y quizs plazos volver a programar en consecuencia.

Solucin Cada proyecto de desarrollo requiere una especificacin, que re fl eje el anlisis de
necesidades realizado conjuntamente por el equipo del proyecto y el cliente.

Escribir la especificacin debera ser mucho como mantener un registro de lo que se ha dicho durante la
discusin de los requisitos. En ninguna parte es tan importante como en este caso que la comunicacin y
documentacin de cara a cara se complementan entre s:

El documento especi fi cacin describe el entendimiento comn del sistema que el equipo del
proyecto y el cliente han conseguido, y proporciona el equipo con la informacin necesaria
para comenzar el diseo.
38 Encontrar los temas correctos

Los casos de uso, historias y escenarios proporcionados por los expertos en el dominio generalmente
proporcionan una excelente entrada para el documento especi fi cacin. A veces, un su fi cientemente
conjunto completo de casos de uso puede ser todo el documento especi fi cacin requiere, siempre que los
casos de uso son su fi cientemente detallada para asegurar que el equipo del proyecto y el cliente han llegado
a un entendimiento comn.

El documento especi fi cacin puede ser utilizado para obtener nuevas conversaciones comenzaron. Usted puede tomar un

primer documento espec fi cacin a los expertos de dominio para la retroalimentacin, por lo que la mejora de la memoria

descriptiva.

Es importante que todas las partes estn de acuerdo en esta especificacin. Esto requiere ms que un
acuerdo general de quien representa la organizacin del cliente en su conjunto. acuerdo de las partes
interesadas requiere un entendimiento comn compartido por el equipo y todos los departamentos de la
organizacin del cliente, de hecho por todas las personas involucradas.

Discusin Por mucho que este patrn hace hincapi en que una estrecha colaboracin con el cliente es necesaria
para producir una buena memoria descriptiva, no se debe llegar a la conclusin de que otros
documentos no requerirn una colaboracin similar. De hecho, todos los documentos del proyecto
hacen. El punto aqu, y la motivacin para este patrn particular, es que el catin requisitos especificados
merece una especial estrecha colaboracin entre el equipo del proyecto y el cliente desde el primer da.
Este principio mucho se ha insistido en la literatura sobre el desarrollo gil. El manifiesto gil (en una de
sus recomendaciones de seguimiento) sugiere que 'la gente de negocios y desarrolladores trabajar
juntos todos los das durante todo el proyecto', como se cita en el libro de Alistair Cockburn (Cockburn
2001). comentarios Alistair Cockburn: '... cuanto ms tiempo se tarda en obtener informacin desde y
hacia los desarrolladores, ms dao se producir al proyecto'. Scott Ambler cita la participacin activa de
los interesados como uno de los principios bsicos de Modelado gil

(Ambler 2002).

El papel de la colaboracin cliente tambin ha sido objeto de muchas otras obras. Por ejemplo, Jim
Coplien, en sus patrones de organizacin, recomienda que se Atraer a los clientes ( Coplien 1995) no
slo en la garanta de calidad, sino tambin en las especi fi caciones y el diseo.

An as, la colaboracin del cliente puede ser difcil, ya que requiere que usted pueda hablar un lenguaje comn. Una
manera de aliviar este problema es planificar para una CRTICA DE CONSUMIDOR.
Fundamentos de diseo 39

Adems, hablando un lenguaje comn es ms di fi culto en abstracto que en el hormign.


Colaboracin con el cliente puede fi nes mucho trabajando en
REALISTA EJEMPLOS a la que tanto el equipo del proyecto y el cliente puede relacionarse fcilmente. Esto es, entre
otras cosas, por qu los casos de uso son tan particularmente til.

Fundamentos de diseo

Problema Cmo puede el equipo asegurarse de que se sientan las bases para futuros cambios de diseo?

Efectivo La mayora de los proyectos eligen para documentar el diseo del sistema que estn construyendo. Un
documento de diseo describe las interfaces del sistema, as como su funcionamiento interno, tpicamente
abordar tanto los aspectos estructurales y de comportamiento. El objetivo de dicho documento es transmitir el
diseo del sistema a otros miembros del equipo, a los clientes o para proyectos futuros.

Tal descripcin diseo es bastante justo, ya que puede resultar til durante el mantenimiento del sistema.

Cuando un sistema experimenta un cambio, sin embargo, una simple cuenta el diseo real podra no ser su fi
ciente. A medida que el diseo evoluciona, es importante que el equipo es consciente de por qu se eligi el diseo
en el primer lugar y lo que podran existir otras opciones de diseo. Sin embargo, los detalles de implementacin es
probable que cambien cada vez que los cambios en el software, por lo que no van a ser de mucha utilidad a largo
plazo.

Solucin Los documentos de diseo se convierten en una valiosa fuente de informacin, si no se


limitan a describir el diseo actual, pero tambin se centran en la razn de ser del diseo y
explican por qu se eligi el diseo particular.

Cuanta ms experiencia revela un documento de diseo, ms til que puede ser para proyectos futuros. Se
trata de las lecciones aprendidas del diseo del sistema que hace que un documento de diseo de una
contribucin valiosa a la documentacin del proyecto. Esto conduce a las siguientes directrices:

El documento de diseo no slo debe estar preocupado con los resultados del proceso de
diseo, pero debe explicar las razones que llevaron al diseo real.

El documento de diseo debe explorar posibles alternativas de diseo, analizar sus pros y
contras, y explicar por qu se rechazaron esas alternativas.
40 Encontrar los temas correctos

La razn de ser de un diseo es lo que es til para los miembros del equipo que necesitan comprender el
funcionamiento interno del software, tal vez porque tienen que mantener, ampliar o mejorar la que, tal vez
porque les gustara volver a utilizar el concepto, al menos parcialmente, en su proyecto, o de otra manera
pro fi ciarse de las experiencias realizadas.

Por otro lado, los buenos documentos de diseo a menudo pueden prescindir de detalles tcnicos de la
codificacin real.

Discusin Este patrn est muy en sintona con el deseo de poner una ENFOQUE EN EL LARGO PLAZO PERTINENCIA. Espec fi
cos detalles de diseo pueden ser de poco inters despus de un tiempo, y por lo tanto podran no requerir
documentacin. El diseo general seguir siendo esenciales aos despus de que el sistema se puso en marcha
primero, sin embargo, y por lo tanto es un buen candidato para la documentacin, junto con las razones que
llevaron al diseo.

La explicacin de los fundamentos de diseo puede obtener de forma significativa por el uso de
REALISTA Ejemplos. Los casos de uso, u otros escenarios, ayudar a explicar los principios detrs del diseo que
fue elegido, as como sus ventajas y desventajas.

El panorama
Problema Cmo se pueden introducir a la gente a un proyecto sin ser confrontado con un diluvio de
informacin tcnica?

Efectivo Cuando la gente ve una pintura en una galera, a menudo paso atrs y mirar desde una corta
distancia. Esto les permite ver la pintura como un todo. Si se encontraban justo en frente de ella,
que sera capaz de ver el detalle, pero la impresin general se perdera.

Por analoga, la documentacin del proyecto a veces se ocupa de muchos detalles tcnicos - espec fi
cacin detalles, detalles de diseo y similares. Estos datos pueden ser cruciales para el xito del proyecto,
y la documentacin de ellos pueden ser tiles. Sin embargo, a veces es difcil ver el bosque por los
rboles. En El hombre Mes Mtica, Frederick Brooks explica: 'mayora de la documentacin falla en dar muy
poca visin de conjunto. Los rboles se describen, la corteza y las hojas se comentan, pero no hay un
mapa del bosque.' (Brooks 1995) de materiales detallada, tan til como lo puede ser para personas que ya
son expertos, no es de mucha ayuda para los nuevos en un tema, que le gustara entender un concepto, o
que necesitan para obtener una introduccin en nuevos materiales .
El panorama 41

Sin embargo, la documentacin tambin debe atender a las personas que an no son expertos, sino que van
a familiarizarse con el proyecto. Pensar en las personas que se unen a un equipo, o piensan de clientes que
mantendrn un sistema una vez que se ha completado. Tales personas necesitan para conseguir una
sensacin para el proyecto antes de que puedan empezar a trabajar en los detalles.

Solucin Una buena idea de un proyecto es mejor transmite a travs de una descripcin de la 'gran
imagen' de la arquitectura que subyace en el sistema en construccin.

Un documento de cuadro grande puede proporcionar una cierta comprensin general:

El panorama se describe la arquitectura general, muestra cmo todo el sistema se compone de


subsistemas y mdulos, y explica los conceptos bsicos del comportamiento dinmico del
sistema.

El panorama general explica los principios de diseo y motiva las decisiones que llevaron al
diseo real.

Los grandes nombres de las imgenes de la tecnologa que es fundamental para la construccin del sistema.

El cuadro grande abstrae intencionadamente sobre cualquier detalle, tcnicas o no, que son
irrelevantes para una visin general.

Preferiblemente, un documento de cuadro grande debe ser bastante corto y conciso - un extenso documento
no poda proporcionar la breve introduccin que la mayora de los lectores necesitan, y probablemente llegar a
ser contrario a la intuicin. Para la gran mayora de los proyectos, 10 o como mximo 20 pginas son
suficientes. El documento cuadro grande puede proporcionar enlaces a otros documentos ms detallados,
siempre que sea necesario, como ilustra la Figura 5.

Ms all de proporcionar una comprensin global, un documento panorama general es perfectamente adecuado
para obtener las discusiones comenzaron. Principalmente debido a un cuadro grande es de inters general,
sino tambin porque es normalmente corto, un documento panorama fi fcilmente lectores NDS. Si necesita
tener una discusin con el equipo o con el cliente sobre cualquier problema relativo a la arquitectura general del
sistema, pasar a la descripcin de la gran imagen alrededor y que tiene un punto de partida perfecto.

Discusin Este patrn muestra cmo puede proporcionar una visin general y sin perderse en los detalles
tcnicos. A pesar del deseo de brevedad, un cuadro grande de documentos a menudo utilidades de la
inclusin de Ejemplos realista, como tales ejemplos
42 Encontrar los temas correctos

Figura 5. Un documento de gran imagen que proporciona punteros a los detalles

ayudan a los lectores tener una idea de la arquitectura. Por supuesto que puede aadir valor a la gran imagen
del documento si se toma la palabra imagen serio y proporcionar
JUICIOSO ESQUEMAS que le ayudan a argumentar su caso. Toda la documentacin se bene fi cios de una CULTURA
REVISIN que otorga a los autores valiosos comentarios. Un documento que presenta el panorama general
puede beneficiarse especialmente de una revisin que se lleva Una vista distante, y por lo tanto se centra en la
impresin general y no en los detalles.

La separacin de descripcin y evaluacin


Problema Cmo pueden los autores evitar la prdida de credibilidad?

Efectivo En los proyectos de desarrollo, gran parte de la documentacin del proyecto se ocupa de anlisis, diseo,
arquitectura, pruebas y similares. La naturaleza de estos documentos es en gran parte descriptiva.

Sin embargo, a veces se le requiere para llegar a una conclusin, hacer una evaluacin, o incluso
llegar a su opinin personal. Tal vez, como ingeniero de software especializado y experimentado, se
le solicita su opinin sobre un determinado
La separacin de descripcin y evaluacin 43

diseo o un cierto concepto. Un documento de estrategia, por ejemplo, incluye tpicamente puntos de vista
personales y concluye con la recomendacin del concepto c uno especfico o estrategia.

Las opiniones personales son an ms comunes en los documentos que surgen de proyectos de
consultora. Si se trabaja en un proyecto de consultora puede ser la parte central de su trabajo para
llegar a una evaluacin o una recomendacin. Podemos ver que tanto el material descriptivo y
opiniones personales pueden ser necesarios y tiles.

Sin embargo, aunque ambas son necesarias y tiles, no son la misma cosa. Es importante
distinguirlos.

Por analoga, vamos a echar un breve vistazo a la esfera del periodismo. Es una buena regla de
oro que usted debe dejar claro si un artculo en un peridico o una revista presenta hechos, o si se
expresa la opinin del autor (Glasser 1992). Podemos adoptar esta regla de oro para nuestros
propsitos. No es un buen estilo para tratar de influir en los lectores al confundir la descripcin y el
juicio
- lectores podran poner en duda el contenido de un documento que parece ser sugerente.

Solucin Autores ganan credibilidad si, en sus documentos, que la descripcin claramente separada de la
evaluacin.

La siguiente tabla muestra ms o menos cmo los diferentes tipos de informacin pueden clasificarse:

Descripcin Evaluacin

Hechos Juicio

observaciones las opiniones del autor

Anlisis Recomendacin

Datos Validacin

Estadstica Interpretacin
44 Encontrar los temas correctos

La separacin de la descripcin y evaluacin debe ser claro para los lectores. Hay varias maneras de
lograr este objetivo:

La separacin de la descripcin y evaluacin puede ser reflejada en la estructura del


documento. Puede reservar ciertas secciones de un documento para el anlisis, y sacar
conclusiones o llegar a una recomendacin en una seccin separada.

Se puede utilizar tcnicas de diseo, tales como cajas especiales, columnas adicionales, o variaciones de
tipo para dejar claro a los lectores de que cierto material no es una descripcin totalmente objetiva, sino
que representa su opinin o las conclusiones que se dibujan.

Adems, se puede dibujar en su dominio de la lengua para apoyar la separacin de la descripcin


y evaluacin. El material descriptivo no debe incluir implcitamente un juicio: adjetivos tales como bueno,
deseable, razonable, til o malo, problemtico, etc., deben usarse con cuidado al describir hechos u
observaciones.

Discusin La separacin de la descripcin y evaluacin contribuye al objetivo general de la presentacin CENTRADO INFORMACIN.
El material presentado en un documento, o en una seccin, se supone que tiene un enfoque claro. Una
condicin previa para un enfoque claro es no confundir la descripcin y evaluacin.

El uso de tcnicas de diseo para apoyar la separacin de la descripcin y evaluacin es


particularmente til cuando se elige para organizar documentos como
ESTRUCTURADO INFORMACIN. A continuacin, puede emplear elementos estructurales, tales como bloques de texto
o dentro de las clulas TABLAS inequvoca, para visualizar la separacin de descripcin y evaluacin. Del mismo
modo, la El uso cuidadoso de variaciones de tipo
puede hacer que la separacin claramente visible.

Los ejemplos realistas

Problema Cmo puede explicarse abstracto material de una manera comprensible?

Efectivo La mayora de la gente trabaja mejor de lo concreto a lo abstracto que a la inversa. Material tcnico, sin
embargo, a veces es culto abstracto y di fi de entender. Por otra parte, no todos los lectores de un
documento de proyecto son necesariamente expertos en el campo. El material es generalmente
presenta con ms xito cuando se acompaa de ejemplos convincentes.
Los ejemplos realistas 45

Por otra parte, los lectores son a veces escptico cuando un documento slo da consejos generales. Los
ejemplos pueden proporcionar evidencia de que lo que se dice en un documento es informacin sustancial.

Sin embargo, los ejemplos 'juguete' pueden tener el efecto contrario en los lectores. Cuando un punto
importante se explica slo con un ejemplo de juguete, los lectores se les hace creer que el punto no es
sustancial, y que una solucin sugerida podran no funcionar en casos prcticos.

Por otro lado, grandes ejemplos o un gran nmero de ejemplos extensos pueden romper el flujo de un
documento y pueden aumentar su volumen innecesariamente. Incluyendo ms material ejemplo de lo
necesario no es deseable, ya sea.

Solucin Los documentos del proyecto son mucho ms convincente si incluyen ejemplos reales de
contexto del proyecto.

Las discusiones entre el equipo o con los clientes normalmente revelar muchos ejemplos
apropiados:

Cuando se especifica el software con su cliente que normalmente va a desarrollar casos de uso y
escenarios. Estos casos de uso y escenarios representan una valiosa aportacin a un documento fi
especificacin. En algunos proyectos que pueden compensar toda la memoria descriptiva.

Al explicar un diseo tcnico o la arquitectura del sistema, todava es una buena idea que
depender de ejemplos de casos de uso tpicos. Esto hace que su explicacin ms fcil de seguir y
demuestra que el diseo de su fuerza a los problemas correctos.

proyectos de consultora no se refiere necesariamente a una tarea de desarrollo concreto y


pueden no tener casos de uso concretos para confiar. ejemplos realistas son todava tiles, tales
como los escenarios tpicos de dominio del problema.

Cuando ejemplos realistas son demasiado grandes para ser presentado en su totalidad, es aceptable utilizar
slo un extracto o ignorar detalles irrelevantes. Es importante que los ejemplos se toman a partir de material en
el mundo real, sin embargo.

Discusin Este patrn se aplica a casi todos los documentos de la CARTERA DE DOCUMENTACIN. Cuando se lleva
a cabo la ESPECIFICACIONES como un esfuerzo conjunto con el cliente, se puede aprender de los casos de
uso y escenarios, y se puede incluirlos en sus documentos tambin. Cuando se prepara un
documento de diseo,
46 Encontrar los temas correctos

puede ilustrar la FUNDAMENTOS DE DISEO con ejemplos que demuestran las ventajas y desventajas de
las alternativas de diseo del proyecto pueda tener. Al elegir ejemplos, hay que tener en cuenta que
la lectores de destino
para el documento son. Usted tiene que adaptar los ejemplos a los orgenes y las expectativas de
los lectores previstos, de modo que puedan entender los ejemplos y los ejemplos prueban tan
tiles como pretenden.

Informes de experiencia
En lo que sigue me gustara presentar algunos informes de experiencias que muestran cmo se
aplicaron los patrones de este captulo en varios proyectos del mundo real. Me referir a varios
proyectos de la lista al comienzo de este libro. La primera cosa que viene a la mente es cmo

Requisitos diferentes los requisitos de documentacin eran en estos proyectos. Por un lado, tener un proyecto de
desarrollo tales como Paracelso. El equipo era pequea y la colaboracin con el cliente muy cerca.
individuales
Todo el mundo saba lo que estaban haciendo desde el principio, y contando con poca
documentacin haba ningn problema. Los documentos producidos eran de peso ligero, en un
sentido positivo.

Proyecto Paracelso: documentacin mnima


En este pequeo proyecto de la tarea estaba claro desde el principio: el cliente necesita ciertos componentes para la
transformacin de datos que se van a integrar en un marco que estaban construyendo. La estrecha colaboracin surgi de
forma natural. El equipo y el cliente decidi desde el principio que una mnima cantidad de documentacin sera su fi ciente.

La especificacin que se produjo consista esencialmente en las notas que alguien haba tomado durante un
pequeo taller en el que el cliente explic lo que se supona que los componentes de hacerlo.

Simultneamente con el diseo y la codificacin, el equipo elabor un documento de diseo y un concepto de uso. El papel
del diseo documenta las ideas bsicas detrs de los componentes de transformacin de datos. El documento fue puesto a
disposicin del cliente como entrada para un segundo taller, en el que el equipo y el cliente comprueba que el diseo de los
componentes y el diseo de la estructura general eran compatibles, comenz antes de la codificacin. El concepto de uso
proporciona informacin acerca de cmo podran ser llamados los componentes, los parmetros que deban ser suministrado
y as sucesivamente. El cliente utiliza este concepto mucho cuando se integran los componentes en su marco.
Informes de experiencia 47

Considere Proyecto AirView. El documento especi fi cacin se centr en la definicin de casos de uso. A
medida que el equipo haba elegido para construir un prototipo, una especificidad muy largo cacin de la
geometra de interfaz de usuario se hizo innecesaria. El equipo haba entendido que la discusin de la interfaz
de usuario utilizando el prototipo era mucho ms eficaz que la produccin de las especificaciones sin fin. Por lo
tanto, la cantidad de documentacin podra reducirse de forma significativa.

AirView Proyecto: GUI las especi fi caciones

El objetivo del proyecto era desarrollar una nueva interfaz grfica de usuario, por lo que una tarea importante era especificar lo
que la interfaz debe ser similar. Sin embargo, el equipo del proyecto y el cliente de acuerdo en que el documento especi fi cacin
no debe incluir una fl integracin global super descripcin de la geometra de interfaz de usuario. La especi fi cacin de
documentos de fi nen los casos de uso de la interfaz sera poner en prctica, pero intencionalmente en los detalles de la
apariencia visual. La especi fi cacin de los casos de uso result ser bastante importante. Fue hecho en conjunto por el equipo del
proyecto y el cliente, y el proceso de la comisin de los casos de uso de papel a clari fi cados muchos detalles.

Para describir la geometra de interfaz de usuario, el equipo en su lugar opt por construir un prototipo. Este prototipo actu como
un ser vivo especificacin. Se le ha dado al cliente para revisin, podra ser adaptado rpidamente, y proporcion gran parte de
entrada, tanto ms rpidamente y ms concretamente de un resumen especificacin podra haber hecho.

Por otro lado, algunos proyectos requirieron una documentacin ms detallada.

Proyecto Flexicar (vase la pgina 48), por ejemplo, requiere una documentacin ms amplia debido a
que muchas personas estaban involucradas, y porque estaba claro desde el principio que el
mantenimiento del sistema con el tiempo sera entregado desde el equipo del proyecto para el cliente.

A continuacin, hay Proyecto liberarse (vase la pgina 48). Este proyecto fue un gran esfuerzo de
reingeniera. Una especi fi cacin de lo que el nuevo sistema debe ser similar no fue suficiente. El equipo
siempre tena que seguir la migracin del sistema antiguo al nuevo sistema en mente. Esta migracin fue
crucial para el xito del proyecto, y que era necesario documentar, de manera que las numerosas partes
interesadas podran examinarlo.

Proyecto persistor fue un gran esfuerzo, que involucra a muchas personas de diferentes equipos y
diferentes empresas. Debido a que el objetivo de este proyecto era desarrollar un marco, ms
documentos de la CARTERA DE DOCUMENTACIN convirti
48 Encontrar los temas correctos

Flexicar Proyecto: Descripcin detallada del diseo

Cuando se inici el proyecto, el cliente ya tena una idea clara de cmo su proceso de fabricacin de automviles podra ser
mejorado y acelerado. El equipo del proyecto era todava pequeo en el momento, y produjo un documento general que resume
los requerimientos del cliente. El documento tambin esboz la arquitectura, el equipo tuvo en cuenta. El cliente revis el
documento, asegurando que el equipo se diriga en la direccin correcta. El jefe de diseo a continuacin, configurar un
documento que describe la arquitectura del sistema con ms detalle, re fi nir este documento como el proyecto avanzaba. Este
documento fue bastante tcnica, ya que estaba destinado principalmente para los ingenieros de software. El documento sirvi a
dos propsitos. En primer lugar, se utiliza para comunicar los principios detrs de la arquitectura de todo el equipo. En algn
momento, el proyecto consisti en un mximo de 50 personas, por lo que no poda basarse en la comunicacin verbal solo. El
documento de diseo facilita claramente el intercambio de conocimientos. En segundo lugar, el documento fue ms tarde para
ser utilizado por los miembros del equipo del cliente, que eran para mantener el sistema ms all del marco de tiempo del
proyecto.

Proyecto liberarse: mapeo de viejo a nuevo


Este proyecto se enfrent a dos retos principales. En primer lugar, se trataba de muchas personas: el equipo de proyecto,
ingenieros de software por parte del cliente, y expertos en el dominio del cliente. Cada una de estas partes tenido contribuciones
que hacer, y cada uno tena que tener su opinin. En segundo lugar, ya que ste era un proyecto de reingeniera, el equipo primero
tuvo que familiarizarse con el sistema antiguo y su dominio de aplicacin.

El funcional especificacin fue fcil: la funcionalidad del sistema no iba a ser cambiado en absoluto. El sistema tuvo que ser
rediseado para ser ms flexible sin embargo. El equipo tuvo que buscar en el sistema de propiedades no modificables de los
productos de seguros de vida, y tuvo que entender lo que significan estas propiedades para que con precisin se podan
extraer en una base de datos. Esto implic varios detalles sutiles e intrincadas, que fcilmente pasaban desapercibidos durante
las discusiones con el cliente. A menudo, los expertos en el dominio tomaron las cosas por sentado que los ingenieros de
software ni siquiera haban pensado.

Un documento fi especificacin fue de gran ayuda en cuanto a la deteccin de tales malentendidos se refiere. La
especificacin representaba lo que el equipo haba entendido de los diversos productos de seguros, y se le dio a los expertos
de dominio para su revisin. Los expertos en el dominio utilizan la especificacin para verificar el mapeo de las antiguas
propiedades, codificados de forma rgida a las nuevas propiedades. Los debates generados por este documento revelaron
muchos detalles importantes. El documento se actualiza varias veces despus de la discusin, y sirvi como una fuente
confiable de informacin.
Informes de experiencia 49

Otro documento era particularmente importante: el documento de estrategia de migracin. En primer lugar, revel la
dependencia entre la migracin de los diferentes subsistemas - los subsistemas que haba que emigraron antes que
otros y as sucesivamente. En segundo lugar, el papel de la migracin demostr que haba un compromiso entre la
calidad del nuevo modelo de datos y la complejidad del proceso de migracin: cuanto mejor sea el nuevo modelo de
datos era, cuanto ms complejo es el mapeo de viejo a nuevo se convertira. Por otro lado, cuanto ms simple se
mantuvo la migracin, los ms fl AWS se llevara a partir del modelo de datos antigua a la nueva. El cliente aprecia esta
discusin mucho.

necesario. En primer lugar, esto inclua un concepto de uso. Los usuarios marco tenan que aprender a
incorporar el marco en sus aplicaciones: mientras trabajaban en diferentes sitios, la documentacin era
indispensable. En segundo lugar, la documentacin marco incluye un concepto de diseo que se
necesitaba para el futuro mantenimiento y refactorizacin (vase la pgina 50).

Estos informes de la experiencia demuestran claramente que los proyectos tenan INDIVIDUAL DOCUMENTACIN
REQUISITOS. Algunos proyectos fueron multa con un mnimo de documentacin, mientras que otros han
estado en serios problemas sin la documentacin ms completa. La idea clave de la documentacin
gil es no ir sin la documentacin completa en cada uno de los proyectos, pero para asegurarse de
que todos los documentos se justifican fi cado por el beneficio que representan para la A quin va
destinado.

A pesar de los requisitos de documentacin varan, hay varias cosas que, en mi experiencia, todos
los proyectos exitosos tienen en comn, en lo que se refiere a la documentacin. Al revisar los
proyectos Para averiguar en qu tipo de documentacin que funcion y lo que no, me di cuenta de
algunas cosas una y otra vez.

La necesidad de una En primer lugar, ningn proyecto puede prescindir de una memoria descriptiva y proyectos giles no son una

especificacin excepcin. Casi todos los proyectos de desarrollo Mir a los documentos producidos especi fi cacin, y
aquellos que no se arrepinti de esta estrategia. Los informes de la experiencia de proyectos Flexicar,
liberarse y persistor muestran que todos ellos producen una especificacin (o recibieron una parte del
cliente), y todos ellos hacen un buen uso de ella.

De todos los documentos fi caciones que he visto, algunos eran ms bien corto, algunos eran ms detallada. En la
mayora de los casos, una menos detallada especificacin haba ninguna desventaja, debido a que muchos detalles
espec fi cacin nica evolucionado con el tiempo. Proyectos de Paracelso y AirView demuestran que es ms crucial
para el xito a lo que se refiere
50 Encontrar los temas correctos

Proyecto persistor: documentar un marco


Documentacin jug un papel importante, ya que este proyecto participaron muchas personas de muchas empresas, incluso en
diferentes ciudades, y debido a las contribuciones de las diferentes partes tuvieron que ser integradas estrechamente. El equipo
trat de mantener la documentacin en mrgenes razonables, sobre todo con el xito, aunque tambin con algunos problemas.

Despus del saque inicial del proyecto, el equipo produjo una especi fi cacin inicial del marco de capa de acceso a datos.
La especificacin fue bastante corta, obtuvo la aprobacin del cliente, y se utiliz como base para el diseo. Sin embargo,
como el proyecto evolucion, requisitos adicionales salieron a la luz, algunos de los cuales se ejecutaron, otros no. En el
calor del proyecto, sin embargo, estos requisitos adicionales nunca fueron especificados en la escritura. Despus de un
tiempo esto llev a conflictivas puntos de vista sobre las funciones adicionales tuvieron que ser implementado y que
haban sido disminuido. En este punto, la relacin entre el cliente, los desarrolladores de marco y de los otros proyectos se
hizo bastante tensa. El principal problema no era que haba con fl puntos de vista contradictorios, pero que el conflicto no
se ha resuelto de manera adecuada cuando haba surgido primera fi. Todas las partes consideraron que la especificacin
de los requisitos adicionales por escrito, habra sido til, no introducir la burocracia en el proyecto, pero para aumentar la
conciencia de lo que eran necesarios cambios, que estaba a cargo, y las consecuencias sobre los horarios. El problema
ms importante que enfrenta el proyecto era cmo entrenar a los otros equipos para integrar el marco en sus aplicaciones.
Como participaron equipos de diferentes ciudades, comunicacin cara a cara sola era insu fi ciente. El equipo decidi usar
una mezcla de documentacin y talleres. Un concepto de uso para el marco se pas a todos los dems equipos. Este
documento explica cmo el marco podra ser con fi gurada para su uso por una aplicacin concreta, la forma en que se
podra llamar sus mtodos de interfaz, y las directrices generales que deben seguirse. Una vez que los equipos se haban
familiarizado con las ideas detrs del marco y las pautas de uso, el equipo corri marco de talleres en los que se explican
en detalle cmo adaptar el marco a las necesidades del proyecto individual. Estos talleres se llevaron de varios das a
varias semanas, complementando el entendimiento de que el concepto de uso haba suministrado.

Aunque las pruebas jug un papel muy importante, el equipo, junto con el cliente, decidi que la documentacin de los casos de prueba
era innecesaria. En su lugar, el equipo puso en marcha un gran nmero de casos de prueba, y se extendi y se mantiene el cdigo de
prueba como el proyecto avanzaba. A medida que las pruebas fueron ejecutable, que sirvieron al proyecto mucho mejor que cualquier
documento de prueba podra haber hecho.
Informes de experiencia 51

Navegador de proyectos: confusin debido a la falta de especi fi cacin

Este equipo tuvo que desarrollar varios elementos de la interfaz de usuario que eran bastante complejas en su apariencia y su
comportamiento. El marco de tiempo era bastante corto y los plazos eran apretado. El desarrollo de software tena que ser rpido y
ligero documentos eran una necesidad. El equipo del proyecto y el cliente haban acordado los siguientes documentos para cada
componente de interfaz de usuario: una breve especificacin que describe la apariencia y el comportamiento, un documento de
diseo que consiste en un diagrama UML y una descripcin de la interfaz, y un documento sobre los casos de prueba.

Tena que haber un acuerdo sobre la especificacin, no slo entre el equipo y el cliente, sino tambin con el cliente del cliente
- el fabricante de automviles que en ltima instancia comprar el sistema de navegacin. Por desgracia, el cliente final era
siempre tarde en comprometerse con un determinado interfaz grfica de usuario especfico de cationes, pero inst al equipo
para comenzar con el diseo y la implementacin, sin embargo. En algn momento, se pidi al equipo para comenzar la
codificacin, aunque las especificaciones de componentes no estaban disponibles. Cdigo fue escrito - pero ms tarde tuvo
que ser reescrito por completo.

En retrospectiva, el equipo consider que el proyecto tendra pro fi ciado si no hubiera intentado hacer sin especificacin escrita.
Un documento de especificacin podra tener clari ed fi qu partes de la memoria descriptiva se resolvieron y que todava estaban
abiertas. El diseo e implementacin podran se han centrado en aquellas partes que eran claras, dejando espacio para que los
cambios en los puntos calientes. Sin ningn tipo de especificacin, el equipo consider que no estaban recibiendo ni de lejos el
resultado deseado, y la moral era baja.

De lo contrario, la documentacin de peso ligero funcion bien. Los documentos de diseo y los documentos de prueba consista en
slo unas pocas pginas cada uno, pero no contenan toda la informacin necesaria para el cliente para integrar los componentes.

el ESPECIFICACIONES como un esfuerzo conjunto que para completar la especificacin hasta el ms mnimo
detalle. En otras palabras, un incompleto especificacin puede ser fi no, siempre est claro que es
incompleta, y siempre est claro qu partes estn an por decidir.

En algunos casos, sin embargo, un proyecto no tena una especificacin en absoluto. En una etapa Navegador
de proyectos sufri este destino. Sin escrita especificacin estaba disponible hasta bien entrado el proyecto:
algunas declaraciones informales eran todo el equipo podra confiar cuando se les pidi que comience la
codificacin. Al final, tanto cdigo tena que ser borrado y reescrito. Como consecuencia, la moral entre el
equipo fue baja.
52 Encontrar los temas correctos

Proyecto persistor hizo producir una especificacin, pero no pudo mantenerla a lo largo del proyecto y, en
particular, en el transcurso de varias solicitudes de cambio. Como consecuencia, los malentendidos acerca
de la especificacin se convirti en una molestia cada vez mayor. Un mejor mantenimiento de la
especificacin habra hecho las cosas ms fciles para todas las partes involucradas.

visiones generales Una segunda observacin que he hecho es que ningn proyecto puede ir sin EL PANORAMA. Cualquiera que
sea el nivel de detalle necesario para la documentacin de su proyecto, siempre se necesita una visin
general del sistema que estamos construyendo.

capa de objetos

de versiones

El acceso de base de datos

activo pendiente inactivo

Figura 6. persistor Proyecto: el panorama general de la arquitectura de mltiples capas marco de capa de aplicacin
Informes de experiencia 53

Proyecto persistor ofrece un buen ejemplo. En este proyecto, el equipo produjo una especificacin,
un concepto de diseo, un concepto de uso y casos de prueba. Aparte del concepto de uso, lo que
fue muy utilizada por los usuarios del programa marco, la informacin que ha recibido mayor
atencin fue 'cuadro grande' del sistema que se present en el documento de diseo. El panorama
era esencialmente un diagrama que muestra la arquitectura de varios niveles, demostr el acceso a
base de datos y explica los diferentes estados de objetos. Se muestra en la Figura 6. El equipo
utiliz este diagrama mucho cuando se ha de fi nido la arquitectura del marco, y lo utiliz para
comunicar la arquitectura de los otros equipos.

Proyecto Vista tambin se bas en un documento panorama mucho - en realidad este proyecto
vivi en EL PANORAMA. El panorama aqu es un diagrama que describe entorno de las aplicaciones de
la organizacin, como se muestra en la Figura 7. El diagrama en s no contiene muchos detalles. Por
ejemplo, las interfaces entre los sistemas no son adecuadamente especi fi cado. Sin embargo, este
diagrama se utiliza en tantas discusiones y evocaba tantas buenas ideas que el proyecto no habra
sido lo mismo sin l.

Proyecto Vista: discutir el entorno de las aplicaciones


Analizando el entorno de las aplicaciones involucrado hablando con muchas personas, as como navegar a travs de la
documentacin existente. Result que algunas de las interfaces del sistema se documentaron en detalle, mientras que otros no
se documentaron en absoluto. Sin embargo, el problema principal era que nadie saba exactamente lo que existan relaciones
entre los sistemas. Incluso era difcil de obtener una lista completa de todos los sistemas implicados. Una visin general fue
mucho de menos. Uno de los principales resultados de este proyecto fue el diagrama general de la aplicacin paisaje
determinado en la Figura 7, en el que las cajas representan los sistemas y las flechas representan los distintos tipos de
relaciones entre estos sistemas. Esta gran diagrama de imagen se utiliza muchas veces para conseguir comenz una discusin.
Se puso el cliente 'enganchados' inmediatamente. Muchas personas lo miraron, hicieron adiciones y correcciones, y as siempre
una gran cantidad de informacin valiosa. El diagrama se actualiza varias veces durante el proyecto con cada paso hacia
adelante el anlisis del sistema de hecho.

Un documento completamente diferente se dedic a los riesgos tecnolgicos que el proyecto haba identi fi cado. Los
riesgos fueron juzgados con respecto a su relevancia, as como su probabilidad.

Proyecto Webber (vase la pgina 56) es otro ejemplo de la importancia EL GRAN IMAGEN puede ser. El
objetivo de este proyecto era bastante pequeo para configurar un sitio Web, y el cliente fue mucho ms
que ver con el diseo del mapa del sitio.
54 Encontrar los temas correctos

Cliente

Clientes

comisiones replicacin
RES Clientes Los clientes de VITA

Ventas

Puntos de venta

RES (seguro de VITA (seguros


propiedad) de vida)

Clientes contratos

Control de acceso

contratos Pago
LDAP

Administracin
Pago
de cuentas

Banco

Estadstica

actualizaciones Seguro de vida

Pago
Automvil

Tenedura de libros Controlador Recursos humanos

Clientes

Figura 7. Vista Proyecto: el entorno de las aplicaciones


Informes de experiencia 55

Como consecuencia, el diagrama que dio una visin general del mapa del sitio se convirti en el documento
ms importante (Figura 8).

Proyecto OpenDoors muestra los problemas que surgen de no tener un documento 'gran cuadro'. En
este proyecto, el equipo produjo documentacin bastante completa en el portal se desarrollaron,
algunos de los cuales era til y algunos de los cuales no lo era. Como no haba ningn documento
que describe la arquitectura general del portal, la obtencin de una visin general era difcil, y vistas
inconsistentes de la arquitectura general emergi.

OpenDoors proyecto: comunicar el diseo


Como este proyecto consisti en varios equipos, un cierto grado de documentacin era necesaria para gestionar la
comunicacin entre estos equipos. Sin embargo, poca documentacin fue producido para la especi fi cacin del portal
web. La razn fue que la especificacin se realiza cuando el equipo todava era pequeo, y que las personas, tanto de
la compaa de software y el cliente estuviera en ese equipo.

Cuando se trataba de la ejecucin del diseo, sin embargo, ms personas estaban involucrados y la documentacin del diseo
se hizo necesaria. Por desgracia, esto dio lugar a una serie de superposicin de los documentos de diseo, que, al menos en
algunos lugares, ofrecen con fl puntos de vista contradictorios. La documentacin del proyecto era bastante confusa en este
punto. Los equipos individuales haban proporcionado documentos de diseo que describen los subsistemas individuales, pero
no haba ninguna descripcin de la arquitectura global que mantenga todas las partes juntas. Por otra parte, los documentos de
diseo incluyen una serie de detalles que pronto ser obsoleto debido a los requisitos cambiantes. La documentacin refleja el
diseo real. Los diseos individuales de los subsistemas se haban ido por caminos separados, y despus de un tiempo se
convirti en difcil de integrarlas en una arquitectura comn. En ese momento el proyecto decidi consolidar la arquitectura. Esto
fue acompaado por escrito un documento de arquitectura que explic cmo los diferentes subsistemas fueron a colaborar para
formar un portal web. En este documento se hace referencia a algunos de los documentos de diseo anteriores para ms
detalles, pero pro fi ciado mucho del hecho de que podra prescindir de rpido cambio en s detalles.

Estos ejemplos muestran que no slo los grandes documentos de imagen son importantes, tambin
demuestran por qu grandes documentos de imagen son tan importantes. documentos y fotos grandes suelen
construir un puente entre la documentacin escrita y la comunicacin cara a cara. Atraen la atencin de los
lectores y los invitan a preguntar a los miembros del equipo para obtener informacin ms detallada.
56 Encontrar los temas correctos

pgina de inicio

Grupos
comits publicaciones Eventos
regionales

Presidentes y Noreste
revistas reuniones
Vicepresidentes (Berln)

Norte Actas de
Tablero conferencias
(Hamburgo) congresos

Grupos de Inters West Profesional


Especial (SIG) (Bonn) Servicios

Media
(Frankfurt)

Sur
(Munich)

Figura 8. Proyecto Webber: el mapa del sitio

Proyecto Webber: un diagrama de larga vida

Al inicio del proyecto el equipo y el cliente se reuni en una pequea sesin de trabajo para analizar el contenido y la
estructura del sitio Web. Result que el mapa del sitio se supona que era un reflejo de la estructura jerrquica de la
organizacin del cliente. Como resultado, el equipo proporciona un diagrama que dio una visin general de la estructura
prevista (Figura 8). Este diagrama se convirti en la parte central de la especificacin. Este detalles ignorados
intencionalmente tales como el diseo de las pginas web individuales o la lista completa de los hipervnculos que deban
incluirse, ya que estos detalles se cambian con frecuencia. Adems, slo de reflexin pequea fue producido que
describe cmo con fi gura el servidor web y la forma de integrar el contenido en el sitio Web.

El diagrama servido bien a su propsito. Fue utilizado a lo largo de varias discusiones. Despus de que el proyecto de
consultora terminado el cliente sigue utilizando este diagrama para el desarrollo de su sitio Web.
Informes de experiencia 57

Proyectos persistor, Vista y Webber dan una poderosa evidencia de que la documentacin escrita y
la comunicacin cara a cara no se oponen entre s. El mismo fenmeno se puede observar en
otros proyectos tambin.

Credibilidad Mi tercera observacin es que la SEPARACIN DE descripcin y evaluacin


hace mucho bien, aunque muchas personas no son muy conscientes de este principio. Proyecto Vista,
por ejemplo, describe el entorno de las aplicaciones y los riesgos de arquitectura por separado. Proyecto
Contentis hizo una clara separacin entre los requisitos y la recomendacin real de una herramienta.
Ambos proyectos ganaron credibilidad de esta manera.

Proyecto Contentis: requisitos y recomendaciones


El equipo comenz con un anlisis de cmo el cliente desea utilizar un sistema de gestin de contenidos. El equipo
se entrevist con el cliente, el cliente respondi, el equipo inmovilizados lo que haban entendido, y el cliente
revisado lo que estaba escrito. Lo que surgi fue una fi cientemente comprensin exacta de los procesos futuros. A
partir de esta comprensin del equipo deriva una lista de requisitos para el sistema de gestin de contenidos.

A continuacin, el equipo en contacto con varios vendedores y les pidi que ejecutar talleres en los que deben
demostrar cmo funcionaban sus sistemas. Se les dio el documento de requisitos para que pudieran prepararse para
los talleres. Tambin se les dio una descripcin de un caso de uso concreto - el boletn web el cliente quera
implementar. En los talleres los vendedores demostraron cmo el boletn podra implementarse con sus sistemas, y
en qu medida sus sistemas de veri fi c los requisitos.

El equipo concluy el proyecto con un documento de evaluacin que refleja cmo el equipo sinti los diferentes
productos en el mercado coincide con los requisitos. El equipo proporciona tanto: un documento de requisitos,
claramente objetiva, a raz de un anlisis exhaustivo, y un documento de evaluacin, influida por las impresiones de
los talleres. Estaba claro que la recomendacin formulada en el documento de evaluacin incluy puntos de vista
personales. En ltima instancia, fue el cliente que deciden qu sistema que iban a utilizar.

la preservacin de Por ltimo, me gustara subrayar una vez ms la importancia de mantener una ENFOQUE EN EL LARGO PLAZO PERTINENCIA.

la Durante la revisin de muchos proyectos me di cuenta de la importancia de los documentos que describen las
cosas que importan en el largo plazo, especialmente la FUNDAMENTOS DE DISEO. Dos proyectos demuestran esta
Conocimiento
importancia particularmente bien.
58 Encontrar los temas correctos

En el caso del Proyecto persistor, la FUNDAMENTOS DE DISEO fue exactamente lo que faltaba en el
concepto de diseo. La consecuencia fue que el concepto de diseo result ser menos til como
podra haber sido, y el equipo experiment problemas significativa durante el mantenimiento de la
estructura que se podra haber evitado.

Proyecto Flexicar tuvo ms xito en la captura de la FUNDAMENTOS DE DISEO. El documento de diseo


se indica por qu el diseo particular haba sido elegido, llamado los pros y los contras de varias
alternativas de diseo, y se utiliza ejemplos reales para explicar estas decisiones. Esta era una condicin
previa para la longevidad del software, y contribuy en gran medida al xito del proyecto.

Proyecto persistor: di fi cultades con las nuevas exigencias


Dos aos despus del lanzamiento de la primera capa del marco de acceso a datos, la aplicacin del mecanismo objeto de
versiones tuvo que ser cambiado debido a las nuevas necesidades, y con el fin de aumentar el rendimiento del tiempo del
marco. Slo unas pocas personas del equipo original eran todava en el proyecto, y que no estaban familiarizados con los
pros y los contras de las distintas alternativas de diseo que el equipo haba evaluados dos aos antes.

Este fue el momento en que se consult al concepto de diseo. Por desgracia, se dio poca informacin sobre la
motivacin detrs del diseo actual. Se describa los principios del diseo que haba sido elegido, pero no mencion
las razones, ni por qu se ha rechazado ninguna diseos alternativos. Un buen grado de ingeniera inversa hizo
necesario trabajar en lo que existan alternativas y cules fueron las diversas ventajas y desventajas. Haba la razn
de ser del diseo original ha documentado, el equipo habra sido capaz de reaccionar a las nuevas exigencias
mucho ms rpidamente.

Flexicar proyecto: la gestin de la responsabilidad del diseo

El arquitecto principal haba producido un documento de diseo que, a lo largo de los aos, se utiliza en gran medida. En primer lugar,
que representaba un punto de partida ideal para los nuevos miembros del equipo para aprender acerca de la arquitectura del sistema. El
documento no se limit a describir el sistema, sino que tambin explica la motivacin de las decisiones de diseo. Por ejemplo, explica el
documento por qu se utiliz un servidor de aplicaciones y por qu persistencia manejada por el frijol se haba dado preferencia sobre la
persistencia gestionada por contenedor con los (Enterprise Java Beans) EJB, y as sucesivamente.
Informes de experiencia 59

En segundo lugar, cuando el proyecto lleg a su fin, el equipo se redujo y los ingenieros de software de cliente eran para
mantener el sistema. Estos ingenieros de software haban estado en el proyecto, por lo que ya se saba mucho sobre la
arquitectura, a pesar de que no se haban inventado. El documento de diseo, sin embargo, les permiti comprender la
motivacin detrs de las decisiones de diseo que haya uno o dos aos antes. El hecho de que un documento de este tipo de
diseo estaba disponible hace que sea ms fcil para ellos aceptar la responsabilidad del mantenimiento del sistema y las
posibles ampliaciones futuras.
2 estructuracin
Documentosindividual

voluminosa documentacin es parte del problema, no parte de la solucin.

Tom DeMarco, Timothy Lister (DeMarco Lister 1987)

Alguna vez ha buscado algo en un documento y ha sido incapaz de encontrar que, a pesar de que
saba que tena el documento correcto? Es probable que tenga - este problema es bastante comn.

En la mayora de los casos, la documentacin voluminosa no es exactamente un servicio a los lectores. A pesar
de la intencin de ofrecer a los lectores una informacin completa, voluminosa documentacin menudo oculta el
conocimiento cuando en su lugar debe transmitir la misma.

Por desgracia, los documentos del proyecto son a veces bastante largo y mal organizada. Si los lectores
se enfrentan a este tipo de documentos, puede ser edades antes de que hallar la informacin que estn
buscando.

En algn momento se dan por vencidos. Frustrado con ir a travs de un documento una y otra vez,
recurren a otras formas de obtener la misma informacin, o deciden tratar de salir adelante sin l.

Este es el momento en que un documento en ltima instancia ha fallado en servir a su propsito. Ese
documento es una prdida de tiempo, tanto para los que lo escribi y para aquellos que deben leerlo.

Antes de presentar los patrones que se ocupan de este problema, vamos a hacer un pequeo experimento. Me
gustara preguntarle a mirar en los extractos de los documentos del proyecto indicados en la figura 9 y la figura
10, para ver cul prefiere.
62 La estructuracin de los documentos individuales

Los procesos de implementacin para el Contenido Web

Hay esencialmente dos maneras diferentes de publicar contenido en la web: una para los cambios de forma, y el otro para
los cambios estructurales. Cambios de redaccin son hechas por los editores y son desplegados en caliente a la web. Los
cambios estructurales influyen en la programacin de los contenidos, tales como cdigo Java dentro de JSP, y se someten
a pruebas antes de su lanzamiento.

contenido web se almacena y se edit en un sistema de gestin de contenidos (CMS). A continuacin, se explica
con ms detalle cmo los dos procesos de implementacin de la CMS a la web parecen.

Para hacer cambios en la redaccin, agrega un editor o el contenido de las actualizaciones en el CMS. Una vez hecho
esto, un editor en jefe opiniones y publica el contenido. Editorial significa que el editor en jefe llama a una funcin que
ofrece el CMS, lo que resulta en el contenido nuevo o modificado ed desplegarse directamente en el servidor web. El
servidor web no tiene por qu ser reiniciado.

Los cambios estructurales son realizadas por un programador que realiza cambios en la programacin JSP dentro de
las plantillas utilizadas en el CMS. Una vez que estos cambios son fi nalizado, el programador llama a una funcin que
exporta el contenido del CMS en una estructura fi sistema le conoce como el rea de transferencia. A continuacin, el
programador invoca un proceso que transfiere el contenido a un servidor de prueba. El programador entonces prueba
los cambios con un servidor web que se ejecuta en la mquina de prueba. Programacin y pruebas se repiten hasta que
las pruebas tienen xito. Los cambios son ahora listo para ser publicado en la web. Para ello, un administrador del
servidor web detiene el proceso del servidor web, transfiere el contenido modi fi cada de la mquina de prueba al
servidor web, y vuelve a iniciar el proceso de servidor web.

Figura 9. Extracto de un documento de proyecto

Estos dos documentos se ven muy diferentes, a pesar de que contienen la misma informacin. Su
apariencia y estructura no podran ser ms diferentes, sin embargo. El primer extracto consiste en unos
pocos prrafos, mientras que la segunda cuenta con elementos estructurales ms fuertes y un diagrama
para la ilustracin. Curiosamente, el segundo fragmento es ms largo que el primer uno. Pero no es tan
densa, y debido a su estructura mejorada tiene menos de una sensacin voluminosa.
63

Los procesos de implementacin para el Contenido Web

Hay esencialmente dos maneras diferentes de publicar contenido en la web: una para los cambios de forma, y el otro para
los cambios estructurales. Cambios de redaccin son hechas por los editores y son desplegados en caliente a la web. Los
cambios estructurales influyen en la programacin de los contenidos, tales como cdigo Java dentro de JSP, y se someten
a pruebas antes de su lanzamiento.

El siguiente diagrama explica que los sistemas estn implicados.

Desplegar

Exportacin
Desplegar
CMS
Transferir Servidor web

Transferir rea de servidor de prueba

cambios de redaccin

1. Un editor aade o contenido cambios en el sistema de gestin de contenidos (CMS).

2. Un editor en jefe opiniones y publica el contenido. Al llamar a una funcin que ofrece el CMS, el contenido
nuevo o modificado ed se despliega directamente al servidor web. El servidor web no tiene por qu ser
reiniciado.

Cambios estructurales

1. Un programador realiza cambios en la programacin JSP dentro de las plantillas utilizadas en el CMS.

2. Una vez que los cambios son fi nalizado, el programador llama a una funcin que exporta el contenido del CMS en una
estructura de cadena de msica le conoce como el rea de transferencia.

3. El programador invoca un proceso que transfiere el contenido en el servidor de prueba.


4. El programador pone a prueba los cambios con un servidor web que se ejecuta en la mquina de prueba.

5. Pasos 1 a 4 se repiten hasta que las pruebas tienen xito. Los cambios son ahora listo para ser publicado en
la web.
6. Un administrador del servidor web detiene el proceso de servidor de web, transfiere el contenido ed modificado de
la mquina de prueba al servidor web, y re-inicia el proceso de servidor web.

Figura 10. Fragmento de un documento de proyecto, organizado de manera diferente


64 La estructuracin de los documentos individuales

Los lectores pueden acceder a la informacin mucho ms rpido en los documentos que siguen el estilo
del segundo fragmento, que se toma de OpenDoors proyecto. documentacin gil sigue este enfoque y
su objetivo es producir mejores documentos a travs de las siguientes tcnicas:

La idea clave es proporcionar documentos con una estructura til que gua a los lectores a
travs del material, lo que ayuda a obtener la informacin que necesitan.

La inclusin de diagramas significativos puede hacer que los documentos un disparador para la comunicacin
cara a cara.

Una dosis razonable de la meta-informacin informa a los lectores sobre el material que tienen
frente a ellos, para que puedan decidir si el material es para ellos y ver cmo se relaciona con
otros artefactos del proyecto, por ejemplo, el software que se est construyendo.

Este captulo comienza con patrones que toman un vistazo general a la estructura de los documentos, luego pasa
a los patrones que sugieren elementos de hormign se pueden utilizar. La Figura 11 proporciona una visin
general.

Estos patrones no slo para hacer ms accesibles los documentos a sus lectores, sino que tambin
ayudan autores escriben los documentos de proyectos con mayor rapidez. Agregar informacin a un
documento bien estructurado es mucho ms fcil que la actualizacin de un artefacto literario complejo.
Una estructura de documento til allana el camino para documentos ligeros ya un proceso de
documentacin gil. Relacionada con la forma en que se estructuren los documentos del proyecto es el
estilo de escritura que utilice, a pesar de que no est cubierto por estos patrones. En general, un estilo
directo har sus documentos de proyectos bien. Si usted est interesado en los problemas de estilo, me
gustara que lo remita al cuerpo de la literatura. lectores de habla inglesa se hallar Los elementos del estilo por
William Strunk y EB White ms til - corto, preciso y al punto (Strunk Blanco 1979). lectores alemanes
podran bene fi cio de los libros de Wolf Schneider (Schneider 1996, 1999). Por ltimo, me gustara sealar
que los patrones en este captulo no prescriben un estilo de escritura fi co. Todo el mundo tiene su propio
estilo de escritura individual, y esto es definir. En su lugar, estos patrones se ofrecen algunas sugerencias
sobre cmo puede mejorar sus documentos mediante la mejora de su estructura y al hacerlos ms
accesibles a sus lectores.
sesenta y cinco

AMBIGEDADES ESQUEMAS
MESAS juiciosa

a menudo incluye

puede usar
a menudo incluye

La informacin GUIAS PARA


estructurada incluye LECTORES
sealarle

pueden incluir

Thumbnail
Sketches
introducir
el
utiliza a menudo

GLOSARIO
puede usar

incluye Referirse a

Referencias HISTORIA DEL

trazable DOCUMENTO

Figura 11. Los patrones para la estructuracin de documentos individuales


66 La estructuracin de los documentos individuales

La informacin estructurada

Problema Cmo puede la informacin sea presentada de una manera fcilmente accesible?

Efectivo Los documentos del proyecto tienen dos tipos de lectores. Es posible que desee leer un documento de
principio a fin, o puede ser un lector ocasional que est principalmente interesado en la bsqueda de
informacin y que lee los pasajes ms largos slo cuando sea necesario. Idealmente, los documentos del
proyecto deben permitir tanto para la lectura secuencial y para la recuperacin de informacin rpida, por lo
que sirve ambos tipos de lectores.

Robert Horn analiz la comunicacin escrita y encontr que los seres humanos pueden procesar
informacin estructurada ms rpida y ms fiable que la informacin no estructurada (Horn 1989). Los
lectores pueden recuperar informacin con mayor facilidad cuando es precisa clasi fi y estructurado.

La experiencia demuestra que, en efecto, los documentos pobremente estructurados a menudo no cumplen su
objetivo con los lectores ocasionales. lectores ocasionales, cuando buscan informacin especfica, estn
dispuestos a navegar a travs de un documento por un tiempo, pero renunciar cuando su bsqueda resulta
infructuosa y asumir que la informacin no est disponible.

Esto podra sugerir que los documentos del proyecto deben organizarse como hipertexto, el uso de
hipervnculos para llevar a los lectores a travs de las partes de un documento que son relevantes para
ellos. Sin embargo, hay que tener en cuenta que los documentos deben tambin permiten la lectura
secuencial, y que el hipertexto es contrario a la intuicin a leer de principio a fin. Mejora de un texto
secuencial con una estructura rica viene a la mente. Pero hasta qu punto se debe estructurar un
documento? Un estudio psicolgico prominente nos da una pista. En 1956, el psiclogo George A. Miller
observ que las personas son generalmente capaces de identificar y memorizar unos siete piezas de
informacin a la vez (Miller 1956). Esta observacin se puede aplicar a la estructura general de los
documentos. 4 Por ejemplo, un captulo que consiste en significativamente ms de siete secciones es
difcil de manejar para los lectores ocasionales que buscan para memorizar la estructura del
documento. Por otro lado, un captulo que consiste en significativamente menos de siete secciones
parece ser mal estructurada. Lo mismo se aplica a la

4. Estado de las siete de Miller ha sido a menudo mal interpretado y mal. El recuadro de la pgina 67 explica por qu en verdad se puede
aplicar a la estructura de los documentos del proyecto, en cuanto a hacer documentos accesibles a los lectores ocasionales se refiere.
La informacin estructurada 67

Recuadro: el nmero mgico siete


papel pionero de George A. Miller de 1956, ' El nmero mgico siete, ms o menos dos: Algunos lmites en nuestra
capacidad de procesamiento de la informacin '(Miller 1956), ha sido muy referenciado en la literatura sobre ambas
ciencias de la comunicacin y la informtica. Miller llev a cabo una serie de experimentos que probaron la memoria a
corto plazo del cerebro humano. Los experimentos se basaron en un conjunto discreto de estmulos en forma lineal, que
es unidimensional, orden tal como puntos en una lnea, campos o loudnesses. La gente tena que identificar un estmulo
elegido al azar.

La relacin de pruebas con xito frente al nmero total de pruebas se hace ms pequeo como el conjunto de estmulos se hace ms
grande. Miller observ que alrededor de un total de siete estmulos, las posibilidades de precisa fregadero catin identi fi dramticamente.
Esta observacin era independiente del tipo de estmulo - visual, acstica o de otro tipo.

Miller concluye que siete representa un lmite superior en la capacidad humana para el procesamiento de informacin, y
en las reivindicaciones del nmero siete que hay 'algn patrn que rige su apariencia'.

Es importante entender que este lmite de siete aos se aplica:

Cuando los estmulos estn en orden lineal, y

Cuando los estmulos individuales necesitan ser identificados fi

La regla de Miller, por tanto, no dice que una novela no debe tener ms de siete captulos. Es cierto que los captulos de
una novela son, en orden lineal, pero por qu querra alguien para identificar un captulo individual?

La regla de Miller no se aplica a los sitios Web o bien, en el sentido de que un sitio web no debe tener ms de siete pginas. Los
usuarios pueden tener para identificar una pgina individual de un sitio completo con el fin de recuperar alguna informacin en
particular. Pero entonces, los sitios Web no estn organizados de una manera unidimensional.

La regla de Miller se aplica a los documentos tpicos de proyectos de software. Debido a que tales documentos se
estructuran en captulos, secciones, etc., que estn organizados en un orden unidimensional. Y mientras que algunas
personas leen un documento de principio a fin, los lectores ocasionales navegar por un documento, leer algo aqu, y
buscan alguna otra informacin en otro lugar. lectores ocasionales pueden familiarizarse con un documento mucho
ms fcilmente si la estructura del documento - sus captulos y secciones - Cumple 'Regla de los Siete' de Miller.
68 La estructuracin de los documentos individuales

nmero de captulos en todo el documento y el nmero de los incisos a una seccin.

Sin embargo, la regla de siete no dice nada acerca de cmo la informacin debe ser profundamente
estructurado. Captulos, secciones y subsecciones son bastante normal, pero qu pasa con los
sub-subsecciones? No hay un lmite general a la profundidad de los documentos estructurados, pero parece
que la mayora de los lectores prefieren documentos que se estructuran hay ms de tres niveles de
profundidad.

Solucin La mayora de los documentos del proyecto estn mejor organizados como texto secuencial sin embargo, bien

estructurado. Esto comienza con los captulos y secciones bien elegidos, pero tambin puede extenderse a la

utilizacin de bloques de construccin textual coherente en todo el documento.

Vamos a echar un vistazo a lo que esto significa.

El primer paso es organizar los documentos con los captulos significativos, secciones y subsecciones
tal vez. Dada esta estructura, los lectores pueden acceder a la informacin en un documento mucho
ms fcilmente que si la estructura no estaba. La estructura es ms eficaz si se sigue la regla de siete
aos de Miller: unos siete captulos a un documento, unos siete secciones para un captulo y as
sucesivamente.

Puede mejorar la estructura de los documentos mediante la adopcin de un segundo paso. La Figura 12
ilustra una pgina que podra ser tomada de un documento de diseo - una seccin que consta de cinco
bloques de construccin. Qu podran representar estos bloques de construccin? Por el bien del
argumento, vamos a suponer que la pgina se describe una clase, y que los bloques de construccin
representan el nombre de clase, un texto introductorio, un diagrama de clases, una interfaz especfica fi
cacin y un grfico de secuencias de mensajes. A continuacin, puede utilizar las secciones que estn
estructurados de esta manera repetida en todo el documento, que describe todas las clases de forma
coherente. Una estructura consistente para una descripcin de la clase es, por supuesto, slo un ejemplo,
pero una estructura similar podra ser igualmente til en muchos otros tipos de documentos.

Ya sea la estructuracin de las secciones en bloques de construccin tiene sentido depende del documento
actual, o si una clara estructura de captulos y secciones es todo lo que puede, o quiere, lograr. De cualquier
manera, este modelo permite crear un documento bien estructurado y uniformemente equilibrado.

Discusin Para un ejemplo rpido, mirar hacia atrs a la Figura 9 y la Figura 10. Figura 10 presenta la informacin
estructurada, la Figura 9 no lo hace. La estructura es exactamente lo que hace
La informacin estructurada 69

Figura 12. La informacin estructurada - una seccin que consta de cinco bloques de construccin

la diferencia entre los dos documentos, y es evidente que la estructura se suma a la facilidad de lectura
que se muestra en la Figura 10.

Un ejemplo destacado de la informacin estructurada es tarjetas CRC (Beck Cunningham 1989).


Tarjetas CRC proporcionan una estructura comn para describir las responsabilidades de las clases
involucradas en un diseo. La estructura coherente de las tarjetas CRC hace tarjetas CRC rpidas a
seguir y convenientes para trabajar con ellos. La forma de patrn utilizado en este libro es otro ejemplo
de informacin estructurada. Cada patrn consta de cinco componentes bsicos: el ttulo, el problema,
las fuerzas, la solucin y la discusin. La estructura hace que sea fcil para los lectores para identificar
qu parte del patrn se mantiene el tipo de informacin. Etiquetas como problema, fuerzas, solucin y discusin
representar a la meta-informacin que usted, el lector permite, para clasificar la informacin que este
libro tiene reservado para usted.
70 La estructuracin de los documentos individuales

Una idea importante detrs de la estructuracin de la informacin es que el uso de diagramas y tablas
puede hacer que la estructura de un documento ms visible. Esta visibilidad ayuda a los lectores perciben
el contenido de un documento. La figura 12 ilustra esto con dos bloques de construccin que consiste en
un diagrama, y la figura 10 da un ejemplo concreto. En general, ESQUEMAS juiciosa puede proporcionar
excelentes vistas generales, mientras TABLAS inequvoca informacin sistemtica presente. Adems, puede
mejorar la estructura de los documentos por medio del diseo y la tipografa, especialmente con El uso
cuidadoso de variaciones de tipo y mediante FALLO Y CUIDADO SOMBREADO.

Todas estas ideas acerca de la estructuracin de documentos plantean la cuestin de qu secciones y


subsecciones que realmente necesita. Naturalmente, no hay una respuesta general a esta pregunta,
pero hay varios patrones que abordan este tema. Cuando se configura la estructura general de un
documento, asegrese de incluir
DIRECTRICES PARA LOS LECTORES y una HISTORIA DEL DOCUMENTO. A menudo se necesita un GLOSARIO, as
como una seccin con Referencias trazable a otros documentos. Cuando se trata de ms fi estructuracin de
grano fino, Thumbnail Sketches aadido a las secciones del documento da un acceso ms rpido a los
lectores ocasionales. Un final Observacin sobre la regla de siete. Al estructurar un documento, siempre
se debe mantener el principio general de la presentacin La informacin centrada

en el fondo de su mente. No hay ningn punto en la creacin de siete captulos, si usted no tiene suficiente
material para siete captulos. La creacin de un captulo o una seccin es sensato slo cuando se puede de
fi nir su enfoque. As que toma la regla de siete aos con un grano de sal. 5

Diagramas juiciosas
Problema Cmo pueden los autores proporcionar una visin general de las estructuras y procesos de una manera conveniente?

Efectivo Estructuras y procesos juegan un papel importante en la ingeniera de software. La estructura de un sistema de
software describe cmo se organiza el sistema y la forma en que se compone de partes ms pequeas.
Procesos describen el aspecto dinmico del software - la interaccin y el comportamiento impulsado por el
Estado, entre otras cosas.

5. Por ejemplo, el nmero de captulos en este libro es en el extremo inferior de la gama que la regla de siete sugiere, mientras que el nmero
de patrones en cada captulo tiende a estar en (o incluso un poco ms all) del extremo superior.
Diagramas juiciosas 71

Si nos fijamos en las tcnicas de modelado comunes, vemos que los diagramas se utilizan con frecuencia
para describir las estructuras y procesos. UML, por ejemplo, tiene diagramas de clase, diagramas de
secuencia de mensaje, diagramas de casos de uso y otros (Rumbaugh Jacobsen Booch 1998, Fowler 2000).

Esto no es realmente sorprendente - todos sabemos que una imagen puede valer ms que mil palabras.
Diagramas hablan a nuestra intuicin. Tambin existe evidencia cientfica c fi que los diagramas de los
lectores perciben ayuda informacin. Por ejemplo, los libros de Edward Tufte en la representacin visual
de la informacin dan una cuenta impresionante (Tufte 1997, 2001). Por otra parte, hay una razn
psicolgica sutil qu diagramas veces son ms adecuados para explicar el material para los lectores.
Diagramas nos permiten ilustrar informacin de una manera de dos dimensiones, lo que aumenta su
comprensibilidad (Miller 1956).

Hay ms puntos a favor de los diagramas. Los lectores tienden a aburrirse con montonas, textos largos.
Textos que incluyen diagramas son mucho menos montono. Diagramas sirven como llamativos que atraen
a los lectores de forma rpida, y tambin ayudan a los lectores a memorizar informacin. Los lectores suelen
asociar un texto con los diagramas incluidos, de manera que cuando navegan por el texto en busca de
informacin especfico de un tiempo ms tarde, los diagramas les dan orientacin (Tufte 1997,

2001).

Sin embargo, diagramas carecen de los matices que ofrece el lenguaje. A menos que los diagramas son muy
complicados, que contienen menos detalle que el texto. diagramas complicados, sin embargo, pierden gran parte del
encanto que hacen sencillo, 'en su cara' diagramas apelan a nosotros.

Esto nos deja en el dilema que los diagramas solo, por muy valiosas que sean, no pueden
proporcionar una informacin completa, pero a menudo dejan sin contestar preguntas detalladas.

Solucin Los diagramas pueden proporcionar excelentes vistas generales, mientras que un texto que la acompaa explica los
detalles en la medida en que sea necesario.

Buenos diagramas complementan el texto. Un diagrama a menudo describe un todo y sus partes, as
como las relaciones y dependencias que sujetan entre las partes. El texto que lo rodea puede
referirse al diagrama y puede cavar profundamente en la materia.
72 La estructuracin de los documentos individuales

Hay una amplia gama de cosas que se pueden describir muy bien a travs de diagramas. La siguiente
lista no es completa, pero le da una buena idea de los diferentes tipos de diagramas, algunos de los
cuales son bien conocidos a partir de UML (Rumbaugh Jacobsen Booch 1998, Fowler 2000):

una visin general de arquitectura

Los diagramas de clases

Los diagramas de interaccin

diagramas de actividad

diagramas de estado

Los diagramas de despliegue

Por supuesto, no debe estorbar sus documentos con diagramas innecesarios. Si un esquema no
es significativo, ir sin ella. Pero cada vez que se escribe un documento, mantenga preguntando si
hay alguna informacin que se expresa mejor visualmente.

Los mejores diagramas son a menudo los que son clara y sencilla. Idealmente, un diagrama utiliza
slo un nmero bastante reducido de elementos grficos, lo cual, si es necesario, deben explicarse en
una leyenda. A veces, incluso un dibujo pizarra perfectamente estructurado capturada por una
cmara digital hace un diagrama excelente (Cockburn 2001, Ambler 2002).

Discusin Los diagramas son prominentes en una buena documentacin de todas formas, pero son particularmente
importantes en un contexto gil. documentacin Agile da preferencia a comunicar EL PANORAMA anotando ms
de una larga lista de detalles, por lo que un diagrama que suele ser el mtodo de eleccin. Los diagramas
pueden tener una idea de ancho, diagramas pueden conseguir comenzaron una discusin, diagramas de
promover la comunicacin. Debido a que los diagramas son tan buenos llamativos, pueden aumentar la e fi
ciencia de ESTRUCTURADO INFORMACIN. Si decide organizar su documento con la ayuda de una estructura
distinta, la inclusin de diagramas puede llegar a ser muy til, ya que la figura 13 ilustra. los DIRECTRICES PARA
LOS LECTORES casi siempre puede hacer un buen uso de un diagrama para dar una visin general y para
explicar cmo las secciones de un documento se relacionan entre s. En una vena similar, pero en una escala
ms grande, documento introductorio de un proyecto puede utilizar un diagrama para dar una visin general de
toda la documentacin y para explicar cmo los documentos individuales se relacionan entre s. En otras
palabras, un diagrama puede visualizar la Documento horizontal.
Tablas sin ambigedades 73

Figura 13. Mezcla de texto con un diagrama

Tablas sin ambigedades

Problema Cmo pueden autores presentan informacin sistemtica de una manera precisa?

Efectivo informacin sistemtica es comn en los proyectos de software. En un mundo donde el pensamiento analtico juega un
papel importante, la informacin sistemtica se convierte en una herramienta esencial de la operacin.

Piense en todas las listas que cumplir: la lista de todos los mdulos de un sistema, de todos los mtodos de interfaz, de todos

los cdigos de error, de todos los tipos de datos, de todos los paquetes de trabajo, slo para nombrar unos pocos. Ms

ejemplos de informacin sistemtica tambin se encuentran en muchos proyectos: esquemas de clasi fi cacin, pasos de un

proceso, las asignaciones y as sucesivamente. Dicha informacin sistemtica es a menudo objeto de documentacin. Los

miembros del equipo, sin embargo, no estn interesados en la lectura de un texto largo, cuando todo lo que quieren saber

fcilmente se podra presentar como una entrada de la lista.

El uso de tablas para presentar informacin sistemtica es la opcin obvia. Las tablas son claras y
directas. Similares a los diagramas, tablas pro fi ciarse de la ventaja psicolgica que son de dos
dimensiones. Las dos dimensiones estn representadas por las filas y columnas, que permiten que
los arreglos de texto secuencial no puede procesar.
74 La estructuracin de los documentos individuales

De manera similar a los diagramas, tablas pueden hacer un texto menos montona. Aunque slo sea por la variedad
tipogrfica, las tablas pueden atraer la atencin del lector con facilidad. Sin embargo, las tablas tambin tienen la
desventaja de que comparten con los diagramas. Tablas slo ofrecen poca expresividad lingstica. Si el material
requiere un argumento para su explicacin, ms que puede caber en una celda de tabla, una tabla por s sola no
puede ser suficiente.

Solucin Mesas ofrecen un formato compacto para la presentacin concisa e inequvoca de la


informacin.

La siguiente lista no pretende exhaustividad, pero le da algunos ejemplos de materiales sistemticas que
muy bien pueden ser presentados en las tablas:

Espec fi caciones de interfaz (nombre de la funcin, la firma, abstracto, cdigos de error)

Las listas de clases, mtodos, tipos de datos, etc.

tablas de gestin de errores (cdigo de error, la reaccin)

La comparacin de los pros y los contras de una opcin de diseo

Diferentes medidas que deben tomarse en un proceso o una actividad

Paquetes de trabajo y sus plazos

Cuanto ms autnomo de una mesa es, ms fcil es de comprender. Idealmente, los encabezados de
las filas y columnas dan los lectores toda la informacin necesaria para entender la tabla. Informacin
de fondo sobre lo que se presenta en la tabla a menudo tienen que entrar en el texto que lo rodea, sin
embargo.

Discusin Las tablas se encuentran a menudo en el contexto de La informacin estructurada, ya que aadir a la estructura
del documento. La figura 14 ilustra esto. Las tablas pueden ser utilizados para implementar el SEPARACIN
DE descripcin y evaluacin, por ejemplo, dedicar una columna a otra y observaciones a los comentarios, o
mediante la colocacin de los hechos en una mesa y interpr etations en el texto que lo rodea.

La variedad en el diseo ha sido mencionado como una de las ventajas que ofrecen las tablas. FALLO
DE CUIDADO y sombreado le permite generar tablas que se ven bien desde un punto de vista
tipogrfico.
Directrices para los lectores 75

Figura 14. Una tabla claramente estructurado entre texto circundante

Directrices para los lectores

Problema Cmo se puede informar a los lectores potenciales si deben leer un documento, y si es as,
en qu partes deben concentrarse?

Efectivo Las personas que participan en un proyecto de software son tpicamente ocupando diferentes roles que tienen
diferentes necesidades de informacin. Un documento puede ser importante para alguien y completamente
irrelevante para otra persona. Por otra parte, varias personas pueden leer el mismo documento con diferentes
intenciones. Algunos lectores solamente puede ser que desee obtener una visin general del tema, otros
podran estar buscando algn detalle especfico, mientras que un tercer grupo podra querer leer el documento
en su totalidad.

Adems, algunos documentos requieren que los lectores han ledo otros documentos previamente, o de otra
manera estar familiarizados con ciertos materiales. por lo tanto, deben estar informados de los requisitos previos
para la comprensin de un documento de lectores potenciales.

Tambin puede haber dependencias dentro del propio documento. Los captulos de algunos
documentos son relativamente independientes entre s, y los lectores pueden concentrarse en los
captulos en los que estn interesados. Pero a veces
76 La estructuracin de los documentos individuales

los lectores tienen que pasar por un captulo antes de que sean capaces de comprender al otro.

Solucin Algunas directrices breve al comienzo de cada documento pueden informar a los lectores
potenciales de la finalidad del documento sirve y explicar cmo los diferentes grupos de
lectores deben acercarse al documento.

Las directrices deben evitar que los lectores de estudiar los documentos que no contienen la
informacin que necesitan. Tambin deben evitar que los lectores de pasar por un documento
completo cuando slo partes de l son relevantes. Para ello, las directrices deben responder a las
siguientes preguntas:

A quin va dirigido el documento?

Lo que hay dentro, y lo que est fuera del alcance del documento?

Cmo se organiza el documento?

Cules son las dependencias entre los diferentes captulos del documento? Hay un orden
espec fi co en el que leer los captulos?

Cules son las relaciones con otros documentos? Hay otros documentos que se espera que los
lectores que han ledo previamente?

Cmo pueden los lectores obtener una visin rpida de los contenidos?

Es el documento completo, o se describe un trabajo en progreso? Es de esperar que las


actualizaciones? Si el documento es una actualizacin de una versin anterior, qu partes han
cambiado?

Discusin Sin embargo, las directrices para los lectores aparecen en detalle, que estn destinados a acoger al lectores
de destino a un documento. Ellos dicen explcitamente que la
OBJETIVO LECTORES son, frente a ellos, y hacerles saber cmo utilizar el documento. Un diagrama (ver ESQUEMAS
juiciosa) es a menudo el mtodo de eleccin para la descripcin de la organizacin general de un
documento, as como las dependencias entre sus captulos. El diagrama puede servir como una hoja de
ruta para los lectores cuando navegan a travs del documento de encontrar las partes de inters.
Sealando a los lectores cmo pueden obtener una visin rpida es particularmente fcil cuando los
captulos individuales del documento se proporcionan con MINIATURA Dibujos. Es tambin til para referirse a
la HISTORIA DEL DOCUMENTO, ya que informa a los posibles lectores de estado del documento y de los
cambios entre las versiones anteriores.
Thumbnail Sketches 77

Thumbnail Sketches
Problema Cmo pueden los lectores obtener una visin general de los temas tratados en un documento?

Efectivo Es difcil para los lectores de encontrar lo que buscan en un documento que contiene una gran cantidad de

informacin. Las guas pueden decirle a los lectores lo que puede esperar del documento, pero no pueden decir

dnde buscar cualquier detalle especfico. Una clara estructura de captulos, secciones y subsecciones hace que

sea ms fcil para los lectores de encontrar informacin en particular, sin embargo, una estructura clara por s sola

no puede ser suficiente para que los lectores puedan recuperar informacin de forma rpida. recuperacin de

informacin rpida es necesaria, sin embargo. Idealmente, los lectores pueden navegar a travs de un documento

en un nivel alto, y cavar ms profundo cada vez que sienten que alguna parte del documento es particularmente

relevante para ellos. Gerald Weinberg explica en La psicologa de la Programacin de Computadoras: '... los

diferentes usuarios de la documentacin necesitarn diferentes niveles de detalle de la informacin que extraen. El

nivel ms alto se debe simplemente su fi cientemente detallada para indicar al usuario si es o no ser capaz de leer

los documentos '. (Weinberg 1998)

Solucin bocetos en miniatura proporcionan breves descripciones de las secciones de un documento, incluidos
los objetivos generales de la seccin, as como sus principales ideas.

Un documento que suministra bocetos en miniatura permite la lectura secuencial en diferentes niveles
de detalle. Despus de leer un esbozo en miniatura, los lectores pueden decidir si les gustara ir ms
profundo o si hay que pasar a la siguiente seccin.

Hay dos formas de configurar bocetos en miniatura:

Usted puede dejar que cada seccin comienza con una especie de resumen o sumario.

Se puede elegir algunos prrafos de cada seccin, aunque no necesariamente al comienzo,


y el uso de los bocetos como miniatura. tcnicas de diseo se pueden utilizar para su identi fi
cacin.

Ambas tcnicas preservar el orden secuencial del texto, por lo que la gente puede leer el documento de principio a
fin, si quieren, mientras que otros lectores puedan concentrarse en las imgenes en miniatura para una exploracin
rpida.
78 La estructuracin de los documentos individuales

Discusin Este patrn se basa en la idea de La informacin estructurada. Cuando se utiliza una estructura comn
consistente en todo el documento, bocetos en miniatura aparecen repetidamente en el mismo lugar
dentro de una seccin, donde pueden ser fcilmente identi fi cado.

Este efecto se ve reforzado por el El uso cuidadoso de variaciones de tipo, por ejemplo, por el uso de negrita o
cursiva para los bocetos en miniatura. Considere este libro. Se utiliza una forma de patrn coherente.
Para cada patrn, la seccin de problema y el primer prrafo fi de la seccin de solucin forman un
esbozo en miniatura. Puede hallar la idea principal detrs de cada patrn sin tener que leer todos sus
detalles. Las partes en negrita le dan una primera impresin: se puede ir ms profundo, pero no tiene
que hacerlo.

Por ltimo, desde bocetos en miniatura ayudan a los lectores navegar a travs de un documento, es probable
que desee hablar de ellos en el DIRECTRICES para los lectores.

Referencias trazables
Problema Cmo pueden ser documentos vinculados el uno al otro?

Efectivo Cada documento se supone que debe centrarse en un solo tema. Sin embargo, ningn documento puede ser
visto de manera aislada. Siempre hay temas relacionados que necesitan ser entendidos de antemano o
documentos que proporcionan informacin adicional relacionada. Como consecuencia de ello, casi todos los
documentos deben incluir referencias a otros documentos.

Pero qu sucede si un documento se hace referencia no est disponible para el lector? Despus de todo,
el lector se supone que debe buscar esa referencia si se requiere ms informacin. Una referencia a un
documento que est disponible no vale mucho y podra tambin quedar fuera.

Solucin Un documento debe incluir referencias a otros documentos slo si los lectores pueden
obtener esos documentos sin mucho esfuerzo.

Las siguientes reglas generales son tiles:

Las referencias a otros documentos en el mismo proyecto son, evidentemente definir.

Las referencias a documentos de otros proyectos son fi no slo mientras esos documentos
pueden ser distribuidos entre el equipo. No debera haber ninguna referencia a los documentos
que estn restringidos al uso interno o que subyacen a un acuerdo de confidencialidad.
Glosario 79

Casi todas las organizaciones tienen bibliotecas que contienen la literatura estndar de la ingeniera de
software. Las referencias a dichos libros y revistas son fciles de seguir.

Cient fi cos publicaciones que no son fcilmente disponibles son un asunto diferente. Las
referencias a estas fuentes son a menudo difciles de rastrear, y son por lo tanto inadecuado.

Dentro de un proyecto, es til no slo para hacer referencia a un documento relacionado, sino tambin para sealar a los
lectores de manera explcita en el que puedan hallar el documento.

Discusin Usted puede preguntar si las referencias se pueden evitar por completo. los La informacin centrada patrn
proporciona la respuesta. Su objetivo debe ser producir documentos independientes que no estn
llenas de referencias a otros documentos. Sin embargo, con el fin de dar a cada documento un
enfoque claro y para evitar grandes coincidencias entre documentos, no se puede evitar por completo
las referencias. Si no est seguro de si debe utilizar una referencia o incluir material, la inclusin de Thumbnail
Sketches puede representar un buen compromiso. Esta solucin evita superposiciones, en gran medida,
aunque no totalmente, sin dejar de aadir a la libre containedness del documento. La adecuacin de
las referencias tambin depende de quin sea el lectores de destino

de un documento son. Los miembros del equipo normalmente tienen acceso a un conjunto diferente de los
documentos a los clientes, y tambin lo han hecho los miembros del equipo en contraposicin a los gerentes. Al hacer
referencia a otros documentos, es necesario tener esto en cuenta.

Los documentos electrnicos pueden utilizar hipervnculos para hacer referencia a los documentos relacionados. De
esta manera, los lectores pueden navegar de un documento de referencia al otro. Esta es una buena tcnica para los
documentos que estn destinados para su uso en lnea. Sin embargo, muchos documentos de los proyectos estn
destinados a ser impresa, por lo hipervnculos slo son de uso limitado. (Vase tambin la discusin sobre De fcil
lectura-MEDIA.)

Glosario
Problema Cmo pueden autores asegurarse de que los lectores a comprender el vocabulario utilizado en un
documento?

Efectivo Los trminos tcnicos a menudo se producen en la documentacin producida por un proyecto de software. Los
documentos de diseo en particular, no pueden prescindir de trminos que son especfico a la tecnologa utilizada.
Mientras que algunos trminos tcnicos ms o menos
80 La estructuracin de los documentos individuales

pertenecen al vocabulario estndar de ingeniera de software, los lectores podran no estar familiarizados con los
dems.

Por otra parte, muchos proyectos de software utilizan una terminologa que es espec fi ca a la organizacin del cliente o
el dominio de aplicacin, y no todos los lectores que cabe esperar que estar familiarizado con l. trminos de dominio
espec fi cas pueden ser un obstculo, sobre todo a los nuevos miembros del equipo.

Si usted explica todos estos trminos dondequiera que se produzcan, sin embargo, usted dispersa
explicaciones en todo el texto. Esto conlleva el peligro adicional de que en diferentes lugares que ofrece
ligeramente diferentes explicaciones, que no va a hacer que sus documentos de manera ms precisa.

Por otra parte, una explicacin en alguna parte del texto es multa para las personas que leen el
documento de principio a fin, pero no es realmente til para los lectores ocasionales que visitan el
documento en busca de una de fi nicin o explicacin.

Solucin Un glosario puede explicar trminos tcnicos, as como los trminos espec fi cos para el dominio de
aplicacin.

La mayora de los documentos del proyecto pueden bene fi ciarse de un glosario. Los documentos ms tcnicos requerirn

principalmente las explicaciones de los trminos tcnicos, mientras que las especificaciones de requisitos se basan en gran

medida en el vocabulario del dominio de aplicacin. En un primer paso, la creacin de un glosario es fcil:

El glosario enumera todos los trminos espec fi cos pertinentes al documento en orden alfabtico.

Cada entrada presenta una definicin de fi o explicacin que sea entendido por los miembros del
equipo, y quizs incluye una referencia a otras fuentes de informacin.

Si un proyecto requiere varios documentos, y estos documentos tienen glosarios superpuestos, esfuerzo
redundante es la consecuencia. Para evitar esto, se puede utilizar un glosario central y hacer referencia a ella
desde los documentos del proyecto.

Discusin Dar de fi niciones de los trminos de dominio espec fi cas puede no ser fcil. Con respecto a
ESPECIFICACIONES como un esfuerzo conjunto ayuda, ya que casi siempre se puede obtener una buena explicacin por parte
del cliente.

Los lectores deben ser conscientes de un glosario para que puedan utilizarlo. En particular, si se utiliza un glosario
central, el hecho de que existe el glosario al final de todo no siempre es evidente. Mencionando el glosario en el DIRECTRICES
PARA LOS LECTORES ayuda.
Historia del documento 81

Un gran proyecto podra considerar una herramienta glosario - esencialmente una pequea base de datos de
trminos tcnicos y trminos del dominio de aplicacin - que se puede utilizar para extraer una lista de esos trminos
que necesita en un contexto especial. Dicha herramienta gestiona redundancia entre los glosarios de varios
documentos. Debe, sin embargo, ser elegida slo si la gestin de la redundancia de forma manual no es ms rpido.
No hay ningn punto en el uso de una herramienta si la herramienta no hace las cosas ms fciles.

Historia del documento

Problema Cmo se puede evitar la confusin entre las versiones de un documento?

Efectivo Al comienzo de un proyecto que no todos los detalles de lo que debe ser documentados son conocidos.
El proyecto va a evolucionar y sufrir un cambio, y tambin lo hacen los documentos del proyecto. Los
documentos se van a crear, actualizada y ampliada, tal vez muchas veces.

Pero incluso los documentos que se actualizan peridicamente pueden perder la sincronizacin con lo que
describen. No se puede actualizar la documentacin a la misma velocidad que aquella a la que avanza el
programa, de lo contrario se estara actualizando la documentacin sobre una base diaria. La consecuencia es
que en entre actualizaciones, documentacin no es del todo hasta la fecha.

Esto no es un gran problema, siempre y cuando los lectores son conscientes de que lo que leen podra ser un
poco fuera de fecha, y siempre y cuando saben que, mientras tanto, el software puede haber sido desarrollado
an ms.

Solucin Un historial de documentos puede explicar las diferencias en las versiones anteriores de un
documento, y puede relacionar el documento a versiones del software que describe.

Un historial del documento es esencialmente una tabla con una entrada para cada nueva versin. Se
extiende como evoluciona el documento. Cada entrada se asocia tpicamente con un nmero de versin para
el documento, e incluye la siguiente informacin:

El autor de esa versin.

Una breve lista de los cambios realizados desde la ltima versin del documento fue puesto en
libertad.

Si el documento se describe real del software, la versin del software al que se refiere el
documento.
82 La estructuracin de los documentos individuales

De esta manera, los lectores pueden entender como un documento ha evolucionado durante el curso de un proyecto.

Discusin El mantenimiento de un historial del documento slo tiene sentido en presencia de CONTINUO DOCUMENTACIN. El
historial del documento no pretende ser una excusa para que los documentos no estn actualizados, sino que
sirve para cubrir el desfase natural entre versiones.

El historial del documento puede ser parte de la DIRECTRICES PARA LOS LECTORES, o de lo contrario deben ser
remitidos a partir de ah.

Usted puede optar por almacenar versiones anteriores de los documentos importantes en una DOCUMENTO ARCHIVO, especialmente
en proyectos de mayor envergadura. Algunos archivos son capaces de aadir entradas a un historial de documentos de forma
automtica, aunque normalmente esto es posible slo con texto sin formato archivos.

Informes de experiencia
Veamos cmo se aplicaron los patrones en este captulo en la documentacin de algunos de nuestros
proyectos de ejemplo.

estructura del Me gustara comenzar con la idea de La informacin estructurada. Esta idea estaba presente en la
documento documentacin de la mayora de los proyectos, pero algunos documentos demuestran la utilidad de la
informacin estructurada particularmente bien. Volvamos por un momento al experimento al principio
de este captulo. La Figura 10 en la pgina 63 contiene una pgina de la descripcin de despliegue
que OpenDoors proyecto producido. La Figura 9 en la pgina 62 contiene una pgina I burlado para
demostrar la diferencia. Figura 10 Caractersticas La informacin estructurada,

mientras que la Figura 9 no lo hace.

Hay ms ejemplos de cmo la adicin de estructura hace que un documento sea ms legible. El documento de
diseo de de fi ne una estructura de texto Navegador de proyectos que se aplica de manera uniforme a la
descripcin del diseo de todos los componentes. La Figura 15 muestra la descripcin de uno de tales
componentes. La descripcin de cada componente presenta una breve declaracin visin general, una
descripcin de la interfaz, una descripcin de los componentes internos del componente, as como un diagrama
UML. Los diagramas UML comprender la funcionalidad de todos estos componentes: son ESQUEMAS juiciosa.

El concepto de uso del Proyecto persistor est dirigido a los usuarios del marco capa de acceso a
datos. El concepto de uso se explica cmo cada interfaz
Informes de experiencia 83

Caja de navegacin

El cuadro de navegacin es un control de interfaz de usuario que lleva a la entrada del usuario y ajusta los detalles del
mapa actualmente en pantalla.

El aspecto visual de control es la de una pequea caja, con flechas que simbolizan las funciones para mover el rea
mostrada, y las perillas que simboliza el zoom para mostrar diferentes niveles de detalle. Ver la GUI especificacin
para un ejemplo de pantalla. La clase NavigationBox implementa la interfaz para los controles de interfaz de
usuario.

Descripcin de interfaces

clase NavigationBox

// Este mtodo cambia el rea del mapa que se encuentra actualmente bajo // pantalla, ya sea hacia
arriba, hacia abajo, hacia la izquierda o hacia la derecha //. Se necesita la direccin deseada como un
parmetro //.

movimiento public void (sin firmar direccin corta);

// Este mtodo cambia el nivel de detalle que se muestra. // Dependiendo del parmetro que se
pasa al mtodo, // la pantalla ya sea zooms en el mapa en un paso, o // se ampla hacia fuera.

zoom public void (booleano de acercamiento);

Diagrama de clase

<< >> interfaz


ControlIfc

NavigationBox

movimiento

de zoom EventListener

Figura 15. Navegador de proyectos: informacin estructurada aplicada a un documento de diseo


84 La estructuracin de los documentos individuales

4.2.1 Adicin de un objeto

addObject ()

EN OBJECTTYPE : DT DE TIPO
EN Fullkey : DT-KEY
EN EntryDate : DT-FECHA
EN processNumber : DT-NR

Condiciones previas:

ninguna

Funcin:
La capa de acceso de datos proporciona una versin inicial de un nuevo objeto, de acuerdo con la
fecha de entrada y el nmero de proceso pasado a ella como parmetros. Tras la inicializacin, el
nuevo objeto todava puede ser incompleta; componentes se pueden aadir sucesivamente. El
estado del nuevo objeto est pendiente.

La clave que se pasa a esta funcin como un parmetro de entrada es una clave lgica, que pueden o no llevar
informacin aplicacin especfica. Normalmente es generado por un mdulo especfico fi que todas las
aplicaciones pueden utilizar. En caso de que la tecla fi cado se ha usado previamente para la adicin de un objeto,
se devuelve un cdigo de error.

El nmero de proceso es generado por el sistema de gestin de fl ujo de trabajo.

Cdigos de retorno:

RC-OK El objeto se ha introducido y inicializado correctamente.

RC-KEY La clave lgico especificado no est disponible.


RC-DB La base de datos no est disponible.
RC-PARAMETROS La fecha de entrada o el nmero de proceso son ilegales.

Figura 16. Proyecto persistor: un documento bien estructurado


Informes de experiencia 85

mtodo puede ser aplicado. La Figura 16 muestra la descripcin de uno de tales mtodos. La descripcin
de la interfaz se compone de bloques de construccin para la firma, la lista de parmetros, condiciones
previas, una descripcin y los cdigos de error. A lo largo de todas las descripciones de los mtodos, la
firma, la lista de parmetros y el primer prrafo de la ficha de descripcin Thumbnail Sketches para cada
funcin. Los cdigos de error para cada funcin se presentan utilizando TABLAS inequvoca.

elementos Vamos a echar un vistazo ms de cerca el concepto de uso de Proyecto persistor, ya que cuenta con varios

tiles de los elementos tiles los patrones en este captulo sugieren que deben incluirse en un documento. La
Figura 17 muestra la HISTORIA DEL DOCUMENTO
tomado de una de las primeras pginas del documento. En l se explica el estado del documento,
los cambios que se han hecho al documento en el pasado, que hizo estos cambios y por qu.

Historia

Estado de la versin Fecha autores Observacin

0.1 borrador 1999-Jun-19 A. Rping Primer borrador

Descripcin de la arquitectura

utilizando la interfaz

0.2 borrador 1999-Jun-24 A. Rping Unos pequeos cambios

0.3 borrador 1999-Jun-30 A. Rping Los cambios despus de la revisin interna:

modelo de estado aadi

ejemplo en el control de versiones

aadido

0.4 borrador 1999-Ago-06 A. Rping Unos pequeos cambios:

API de fi niciones

operaciones lgicas
1.0 lanzado 1999-Ago-30 A. Rping Los cambios despus de la revisin externa

2.0 lanzado 1999-Oct-22 A. Rping Actualizar reflejando el lanzamiento de la


nueva versin del marco

Figura 17. Proyecto persistor: un historial del documento


86 La estructuracin de los documentos individuales

La Figura 18 muestra la DIRECTRICES PARA LOS LECTORES, el cual, en el documento original, aparecer al
comienzo de la introduccin. Ellos se refieren directamente a los lectores a travs de unas palabras
introductorias. A pesar de que son bastante cortos, que dejan claro que se debe leer el documento y cmo
est organizado el documento.

Directrices para los lectores

En este documento se describe el uso de la capa de acceso a datos XXXX el nombre que se ha desarrollado en el proyecto XXX
realizado conjuntamente por XXX y sd & m. El documento est destinado a ser utilizado por los miembros del equipo de todos los
proyectos XXXXXX.

La capa de acceso de datos es para ser utilizado por todas las aplicaciones actualmente en desarrollo. En este punto, se trata
del nuevo sistema de seguro de salud y el nuevo sistema de atencin al cliente. Se espera que ms proyectos para comenzar
pronto; van a utilizar la capa de acceso de datos tambin. Para permitir que la capa de acceso de datos a utilizar por varios
proyectos, se ha diseado como un marco. Este marco puede (y debe) ser con fi gurada para reflejar la especi fi cs de un
proyecto que utiliza, en particular, su modelo de datos.

Este documento describe cmo para con fi gura y para usar el marco capa de acceso de datos (liberar 4,0 /
2000-Junio-28). Comenzamos con un bosquejo de los conceptos bsicos de la capa de acceso de datos utiliza, y
luego Describa brevemente su arquitectura. La parte principal de este documento es una descripcin de la API que
explica cada funcin por separado. Directrices para el seguimiento de con fi guracin. Concluimos con algunas pistas
que explican cmo utilizar el marco junto con algunos ejemplos del proyecto de seguro de salud.

Figura 18. Proyecto persistor: directrices para los lectores

La Figura 19 muestra un extracto de la GLOSARIO que aparece en un apndice al final del concepto de uso. Se
explica brevemente los trminos especiales utilizados en el documento, incluyendo tanto los trminos
tcnicos y especificidad del vocabulario c para el dominio de aplicacin.

Finalmente, la Figura 20 muestra la lista de referencias del documento de uso. Son de TRACEABLE REFERENCIAS, como
miembros del equipo pueden obtener fcilmente la informacin
Informes de experiencia 87

Glosario

estado La capa de acceso de datos permite que los objetos estn en diferentes estados: activo, pendientes y

inactivo. En el dominio de aplicacin de estos estados se ajustan a los modos en los que un contrato de

seguro puede ser: vlido, en proceso de revisin, que se ofrecen.

transaccin Una transaccin lgica consiste en la totalidad de pasos a realizar juntos: un caso de uso
lgica atmica. Si un paso conduce a un error o se interrumpe, los pasos anteriores deben hacer
ser deshecho.

transaccin de la Una transaccin de base de datos consiste en una secuencia de escritura / actualizar / borrar los comandos
base de datos que estn bien comprometidos con la base de datos (commit) o ignorados (rollback). Este es el mecanismo
que ofrece una base de datos para implementar transacciones lgicas. En la capa de acceso de datos,
transaccin lgica puede constar de varias transacciones de base de datos. La capa de acceso de datos
utiliza mecanismos de cach para asegurarse de que una reversin lgica es posible.

Figura 19. Proyecto persistor: un glosario

referencias

[* MS] Resumen de gestin, "~ / Arquitectura / summary.doc". [* RS]


Requisito espec fi cacin, "~ / especificacin / requirements.doc". [*ANUNCIO]

Arquitectura y diseo general, "~ / Arquitectura / Arquitectura + design.doc". [GoF]


Erich Gamma, Richard Helm, Ralph Johnson, John Vlissides. Patrones de Diseo,
Addison-Wesley, 1995.

Figura 20. Proyecto persistor: lista de referencias


88 La estructuracin de los documentos individuales

al que se refieren: un par de otros documentos del proyecto y un libro fcilmente disponibles en el diseo
de software.

Diagramas y En todos los documentos de los proyectos que hemos visto en los informes de la experiencia, ya hemos

tablas llegado a travs de varios diagramas que resultaron de gran utilidad. EL GRAN IMAGEN documentos descritos
en la Figura 6, Figura 7 y Figura 8 (pginas 52-56), hacen uso de ESQUEMAS juiciosa, y lo mismo hizo el
concepto de diseo del Navegador de proyectos (Figura 15). Creo que es fcil para que usted pueda
imaginar muchos ms ejemplos - es probable que haya llegado a travs de muchos diagramas tiles en su
prctica cotidiana.

Te voy a dar slo un ejemplo ms. La figura 21 es quitado de Proyecto persistor, y si bien los
detalles de lo que describen los diagramas son irrelevantes, el informe del proyecto explica por qu
los diagramas eran tan til para el equipo.

Proyecto persistor: conseguir la idea a travs de un diagrama


la historia de dos dimensiones es un concepto comn en los sistemas de informacin financieros que separa el momento
en el que se introduce un valor en un sistema desde el momento en que el valor se haga efectiva. El concepto presenta
cierta complejidad algortmica, y explicar en palabras es un asunto complicado, pero diagramas ayudan mucho. Dos ejes
representan la eficacia en una mano y conocido en el momento en el otro (Figura 21). Los intervalos de tiempo aparecen
como zonas acotadas en un avin. Debido a que el marco utilizado la historia de dos dimensiones mucho, el concepto de
uso incluye varios diagramas que explican el concepto. Despus de leer el concepto de uso, alguien del equipo del
cliente dijo: 'Nunca he entendido bien lo que la historia de dos dimensiones se trata. Es tan increblemente abstracto.
Pero ahora que he visto estos diagramas, he finalmente entendi. Varios otros miembros del equipo expresaron
experiencias similares.

No slo los diagramas de aadir estructura a un texto y lo hacen menos montona - lo mismo es cierto para las tablas. Una
vez ms, estoy seguro de que puede pensar en muchos ejemplos, as que slo voy a presentar dos aqu.

La Figura 22 muestra un extracto de una tabla que enumera los requisitos colocados en el sistema de
gestin de contenido Web en el Proyecto Contentis. columnas separadas estn reservados para la
numeracin nica, las necesidades reales y sus prioridades. Sin una mesa, la asignacin de
prioridades a las necesidades no habra sido tan claro como lo es aqu.

La Figura 23 muestra un extracto de la tabla que ilustra las caractersticas de varios productos de
seguros que se utiliza para documentar la reingeniera
Informes de experiencia 89

conocido- en
el momento

2001- reinstalado
conocido- en abril modi fi cada contrato
nio aadi + prima de
el momento

2001- abril nio aadi + prima modi


conocido- en abril 2001 nio
nio aadi + prima modi
fi ed
el momento
marzo fi ed
2001
2001- abril aadi modi prima fi ed
febrero nio aadi + prima modi
abril 2001 nio
2001 fi ed
marzo
enero
2001 contrato original
abril 2001- aadi modi prima fi ed
febrero nio aadi + prima modi
2001
2001 fi ed
marzo
enero nio
2001 contrato original
2001- aadi modi prima fi ed 2001- 2001- 2001 2001- efectividad a
febrero
ene febrero Mar - Abr la hora
2001
enero
contrato original
2001- 2001- 2001- 2001 2001- efectividad a
ene febrero Mar - Abr la hora

2001- 2001- 2001 2001- efectividad a


ene febrero Mar - Abr la hora

Figura 21. Proyecto: persistor diagramas que explican un tipo especial de control de versiones

esfuerzo en el Proyecto de liberarse. Est claro que usted, como lector de este libro, no puede entender los
contenidos de esta tabla, pero creo que se puede medir la importancia que tena para el proyecto. Para todos
los productos de seguros, la tabla indica claramente sus propiedades y demuestra por qu hablamos de TABLAS
inequvoca. La mesa era de gran utilidad para el equipo del proyecto, como el informe del proyecto explica.
90 La estructuracin de los documentos individuales

1.3.2 Hay soporte para diferentes procesos de publicacin? UN

1.3.3 Qu canales publicacin son compatibles? segundo

1.4 Plantillas
1.4.1 Hay un editor de plantillas? UN

1.4.2 Pueden plantillas de organizarse de forma jerrquica? do

1.4.3 Pueden plantillas de heredar caractersticas de las plantillas de los padres? do

1.4.4 Es el nmero de plantillas limitado? UN

1.4.5 Las plantillas ofrecen soporte para marcos HTML? segundo

1.4.6 Pueden incluir plantillas de cdigo, como JSP? UN

1.5 Importacin y exportacin

1.5.1 Qu mecanismos de importacin no proporcionan el CMS (texto, grficos, XML)? UN

1.5.2 Qu formatos de impresin (PDF, etc.) se pueden importar? UN

1.6 de versiones

1.6.1 Hay apoyo para la ramificacin? segundo

Figura 22. Proyecto Contentis: una tabla utilizada para priorizar los requisitos de software

Proyecto liberarse: la informacin condensada en una tabla


Especificando todos los productos de seguros y sus propiedades hasta el ltimo detalle habra sido increblemente compleja.
Pronto result, sin embargo, que lo que el equipo necesita la mayora era una visin general de todos los productos y sus
propiedades - una lista o una tabla, algo sistemtico. Como consecuencia, el equipo desarroll una enorme hoja de clculo en
la que diversos tipos de propiedades fueron asignados a diversos tipos de productos de seguros.

Esta tabla de hoja de clculo se cre primero al comienzo del proyecto, pero se mantiene y se actualiza durante casi dos
aos. Los desarrolladores y los clientes utilizan la hoja de clculo en las reuniones cada vez que se discutieron cmo las
propiedades del producto pueden ser modelados en el nuevo sistema. Hubo ms documentacin que acaba de esta hoja
de clculo, la documentacin que proporcion ms detalles, pero era la hoja de clculo que se utiliz en muchas
discusiones y era ms til.
Informes de experiencia 91

0001 LFE STD 1948-1901 1955-1905 C 1 XNNNRNNNNI P COV


L1R 12 0002 LFE RSK 1948-1901 1955-1905 C 1 1 NNNRNNNNI P COV
L1F 13 0003 REVISIN LFE 1948-1901 1955-1905 C 1 1 NNNRNNNNI S COV
complementar posibles dinmicas de

LG 19 0004 LFE STD 1948-1901 1955-1905 C 1 1 NNYRNNYNGP COV L2S 21 0005 LFE STD 1955-1905 1970-1901 C 2
nmero de generacin estado de los

obligatoria flexible prima reducida

XNNNPNNNNI P COV
prima de terminacin flexible de

modo Poltica de nios fondos


L2R 22 0006 LFE RSK 1955-1905 1970-1901 C 2 1 NNNPNNNNI P COV
tipo complemento de prima
asegurados complementar

L2F 23 0007 REVISIN LFE 1955-1905 1970-1901 C 2 1 NNNPNNNNI S COV


x 29 0008 LFE STD 1955-1905 1970-1901 C 2 1 NNYRNNYNGP COV L3S 51 0009 LFE STD 1970-1901 1990-1910 C 3 1
NYNPNYNYI P COV
fecha de apertura

L3R 52 0010 LFE RSK 1970-1901 1990-1910 C 3 1 NYNPNNNNI P COV


fecha tope

L3f 53 0011 REVISIN LFE 1970-1901 1990-1910 C 3 1 NYNPNNNNI P COV


vieja llave

subtipo

L4S 61 0012 STD LFE 1990-1910 O 4 1 NYNPPYNYI P COV


clave

tipo

L4R 62 0013 LFE RSK 1990-1910 O 4 1 NYNPPNNNI P COV


L4F 63 0014 REVISIN LFE 1990-1910 O 4 1 NYNPPNNNI P COV
LF 70 0015 LFE ETS 1999-1901 C 5 1 NNNRPYNYI P FND
P1 14 0016 PEN IMM 1948-1901 1957-1901 C 1 1 NNNRNNNNI P COV
P2 24 0017 PEN IMM 1957-1901 1963-1907 C 2 1 NNNRNNNNI P COV
P3 34 0018 PEN IMM 1963-1907 1970-1901 C 2 1 NNNRNNNNI P COV
P3D 36 0019 PEN DEL 1963-1907 1970-1901 C 2 1 NNNPNNNNI P COV
P4 54 0020 PEN IMM 1970-1901 1990-1910 C 3 1 NNNRNNNNI P COV
P4D 56 0021 PEN DEL 1970-1901 1990-1910 C 3 1 NYNPNNNNI P COV
P5 64 0022 PEN IMM 1990-1910 O 4 1 NNNRPNNNI P COV
P5D 66 0023 PEN DEL 1990-1910 O 4 1 NYNPPNNNI P COV
I1 15 0024 INV PRINCIPAL 1948-1901 1952-1907 C 1 1 NNNRNNNNI P COV
IG 18 0025 INV PRINCIPAL 1948-1901 1952-1907 C 1 1 YNNRNNYNGP COV
I2 25 0026 INV PRINCIPAL 1952-1907 1970-1901 C 2 1 NNNRNNNNI P COV
I3 55 0027 INV PRINCIPAL 1970-1901 1990-1910 C 3 1 NNNRNNNNI P COV
I3S 57 0028 INV SUP 1970-1901 1990-1910 C 3 1 NNNRNNNNI P COV
I4 65 0029 INV PRINCIPAL 1990-1910 O 4 1 NNNRPNNNI P COV
I4S 67 0030 INV SUP 1990-1910 O 4 1 YNNRPNNNI P COV

Figura extricate 23. Proyecto: una tabla que resume las propiedades del producto de seguro L1S 11
3 Diseo y la tipografa

La consistencia y la repeticin establecer el patrn, que es un aspecto importante del orden [...]. Como
los lectores con experiencia, hemos aprendido a anticipar y esperar patrn.

Suzanne West (West 1990)

En un libro sobre la documentacin gil, un captulo que trata de diseo y la tipografa haba mejor
empezar con una explicacin. Casi puedo escuchar a la gente exclaman: 'Qu diseo y la
tipografa tiene que ver con un enfoque gil? Incluso importa?'

S, ellos son importantes, aunque de una manera bastante sutil. La mayora de los lectores son felizmente
inconscientes de qu es lo que hace que un documento se ven bien. Hay factores que determinan la calidad
del diseo y la calidad del diseo tiene una influencia sobre la legibilidad de un documento que no debe ser
ignorada. Entonces, cul es la conexin de ser gil? documentacin gil sugiere que usted se centra en los
documentos que sean necesarios, y asegurarse de que los documentos necesarios se convierten en
documentos de alta calidad. Alta legibilidad es un aspecto de esa calidad.

Es posible argumentar que los documentos de proyectos no requieren los mismos estndares de calidad con respecto a
la disposicin al igual que los libros impresos, y esto es por supuesto correcta. En una forma gil los documentos del
proyecto no pueden ir a travs de un proceso de diseo muy largo: otras cosas son ms importantes. Nuestro objetivo
debe ser el de encontrar una manera rpida y fcil para producir documentos con un alto nivel de legibilidad.
94 Diseo y la tipografa

Permtanme apoyo la significacin del diseo y la tipografa con los dos puntos siguientes.

La tipografa es un antiguo arte. El arte de la impresin de libros se remonta muchos siglos, ganando
impulso en 1454, cuando Johannes Gutenberg invent la imprenta usando formas de letras
reutilizables. reglas de composicin tipogrfica se han desarrollado y han madurado desde entonces.
La gente no hubiera pasado tanto tiempo en la tipografa si no tuvo ningn efecto sobre la legibilidad.

La investigacin se basa la significacin del diseo y la tipografa. Miles Tinker llev a cabo un
sinfn de experimentos en el medio del siglo pasado y demostr que la mala tipografa ralentiza
la lectura de forma significativa. Sus hallazgos se resumen en su libro sobre la Legibilidad de
impresin ( Gitano
1963). Un estudio realizado en 2000 revel que la tipografa tuvo una influencia en la calidad de las
propuestas a una importante agencia de financiacin y el porcentaje de propuestas exitosas (Berleant
2000).

An sin estar convencido? Mira las pginas que se muestran en la Figura 24 y la Figura 25. Ambas
pginas contienen el mismo material. Qu prefieres leer? Todos esttica a un lado, la pgina que cree
usted que le permite recibir informacin de forma ms rpida y ms fiable?

Creo que es evidente que la segunda pgina es mucho ms legible que la primera, y que diseo y la tipografa es lo

que hace la diferencia entre los dos. Afortunadamente, el camino delante de nosotros en nuestro camino a una

disposicin como la de la figura 25 no es demasiado spera - requiere menos trabajo que uno podra pensar a

primera. Podemos obtener una razonablemente buena disposicin para nuestros documentos de proyectos con muy

poco esfuerzo, y esto es lo que los patrones en este captulo se relacionan. Hay tres razones por las cuales se

necesita poco esfuerzo para mejorar significativamente el diseo del documento:

1. Un bastante pequeo conjunto de patrones puede hacer mucho bien. La regla se aplica 80-20: 80 por
ciento de las ofertas ventajas tipografa se puede obtener mediante el uso de un 20 por ciento de todas
las tcnicas disponibles tipogrficos. Tras una actitud gil, vamos a centrarnos en los patrones que
describen estas tcnicas.

2. Los patrones en este captulo pueden ser fcilmente implementados en la mayora de los procesadores de texto.

3. No todos en el equipo tiene que estar preocupado con estos patrones. Es muy recomendable que
un proyecto, o incluso una organizacin, el uso DOCUMENTO
95

- 20 -

4.2.1 Aadir un objeto

addObject ()

EN OBJECTTYPE : DT DE TIPO
EN Fullkey : DT-KEY
EN EntryDate : DT-FECHA
EN processNumber : DT-NR

Condiciones previas:

ninguna

Funcin:
La capa de acceso de datos proporciona una versin inicial de un nuevo objeto de acuerdo con la fecha de entrada y el
nmero de proceso pasado a ella como parmetros. Tras la inicializacin, el nuevo objeto todava puede ser incompleta;
componentes se pueden aadir sucesivamente. El estado del nuevo objeto est pendiente.

La clave que se pasa a esta funcin como un parmetro de entrada es una clave lgica, que pueden o no llevar informacin
aplicacin especfica. Normalmente es generado por un mdulo especfico fi que todas las aplicaciones pueden utilizar.

En caso de que la tecla fi cado se ha usado previamente para la adicin de un objeto, se devuelve un cdigo de error.

El nmero de proceso es generado por el sistema de gestin de fl ujo de trabajo.

Cdigos de retorno:

RC-OK El objeto se ha introducido y inicializado correctamente.


RC-KEY La clave lgico especificado no est disponible.

RC-DB La base de datos no est disponible.


RC-PARAMETROS La fecha de entrada o el nmero de proceso son ilegales.

4.2.2 eliminar un objeto

deleteObject ()

EN OBJECTTYPE : DT-typw
EN Fullkey : DT-KEY
EN deletionDate : DT-FECHA
EN processNumber : DT-NR

Condiciones previas:

el objeto ha sido previamente aadido

Funcin:

Figura diseo 24. Page: una variacin


96 Diseo y la tipografa

- 20 -

4.2.1 Adicin de un objeto

addObject ()

EN OBJECTTYPE : DT DE TIPO
EN Fullkey : DT-KEY
EN EntryDate : DT-FECHA
EN processNumber : DT-NR

Condiciones previas:

Ninguno

Funcin:

La capa de acceso de datos proporciona una versin inicial de un nuevo objeto de acuerdo
con la fecha de entrada y el nmero de proceso pasado a ella como parmetros. Tras la
inicializacin, el nuevo objeto todava puede ser incompleta; componentes se pueden aadir
sucesivamente. El estado del nuevo objeto est pendiente.

La clave que se pasa a esta funcin como un parmetro de entrada es una clave lgica, que pueden o no
llevar informacin aplicacin especfica. Normalmente es generado por un mdulo especfico fi que todas
las aplicaciones pueden utilizar. En caso de que la tecla fi cado se ha usado previamente para la adicin
de un objeto, se devuelve un cdigo de error.

El nmero de proceso es generado por el sistema de gestin de fl ujo de trabajo. Cdigos de retorno:

RC-OK El objeto se ha introducido y inicializado correctamente.

RC-KEY La clave lgico especificado no est disponible.

RC-DB La base de datos no est disponible.


RC-PARMETROS La fecha de entrada o el nmero de proceso son ilegales.

4.2.2 Eliminacin de un objeto

deleteObject ()

EN OBJECTTYPE : DT DE TIPO
EN Fullkey : DT-KEY
EN deletionDate : DT-FECHA
EN processNumber : DT-NR

Figura diseo 25. Page: otra variacin


97

PLANTILLAS para formar la base de todos los documentos del proyecto. Una vez que estas plantillas se han
diseado de acuerdo a los patrones de diseo y la tipografa, los documentos del proyecto heredan el diseo
grfico de las plantillas. autores individuales fi reglas de composicin tipogrfica primaria nd ya establecidos
antes de que comiencen a trabajar en un documento. Todo lo que se necesita es un poco de disciplina en el
uso de las caractersticas que ofrece el procesador de textos.

La figura 26 da una visin general de los patrones de la que la legibilidad de los documentos de proyecto
pueden bene fi cio. La lectura de los documentos ser significativamente ms cmodo. Los patrones
aseguran que la disposicin es adecuada, si no es perfecto.

dos alfabetos
POR LNEA se corresponde con

permite para

TEXTO EN 50% DE 120%

UN PGINA requiere interlineado

usos

El uso cuidadoso de
dos tipos de letra
variaciones de tipo
puede ser

enriquecido por

pueden formar combina bien


con

su colocacin FALLO DE CUIDADO y


COHERENTE PGINAS
adyacente sombreado
exigir

Figura 26. Patrones para el diseo y la tipografa


98 Diseo y la tipografa

Hay, por supuesto, muchas reglas ms tipogrficos, y los lectores interesados pueden consultar el rico
cuerpo de literatura sobre la tipografa para ms guas (Gulbins Kahrmann 1992, Tinker 1963 West
1990). Sin embargo, para obtener los documentos de proyectos que estn razonablemente bien
diseado y que ofrecen un alto grado de legibilidad, los patrones en este captulo, combinado con una
buena dosis de sentido comn, se bastar.

Una palabra final introductoria: los patrones en este captulo se aplican a los documentos que se van a
imprimir, pero no se aplican necesariamente a la documentacin en lnea. Tendremos una discusin acerca
de lo MEDIA de fcil lectura En el Captulo 4, lo que plantea la cuestin del frente de impresin de entrega de
documentos en lnea. Algunas pautas para la creacin de documentos en lnea se dan all.

Texto en el 50% de una pgina

Problema Cunto espacio en una pgina debe ser dedicado al texto?

Efectivo El diseo de la pgina debe ser esttico si se trata de ser agradable a los lectores. La esttica de la geometra
de la pgina son en gran medida influenciada por el tamao de la denominada 'zona viva' - la zona en la que se
coloca el texto principal, excluyendo los encabezados o pies de pgina. El rea en vivo de una pgina est
rodeado por los mrgenes. Casi todos los lectores prefieren las pginas con amplios mrgenes a las pginas
que parecen estar llena de texto (West 1990).

Los mrgenes no son necesarios por razones estticas solamente, sino tambin por razones funcionales. El margen
interior (tambin llamado el 'saco') debe permitir espacio suficiente para la unin. Todos los mrgenes deben permitir
suficiente espacio para que los lectores tienen una pgina sin ocultar cualquier texto (West 1990).

Sin embargo, los mrgenes que son excesivamente grandes no son apropiados tampoco. Impresin de un
documento requerira ms papel del necesario, lo que es indeseable para econmico, as como razones
ecolgicas.

Aparte del tamao del rea en vivo, su posicin influye en la legibilidad de un documento. El centro ptico de
una pgina es el lugar donde los ojos primero del lector se concentra. El centro ptico est ligeramente por
encima del centro geomtrico de la pgina. Por lo tanto, el rea en vivo debe ser un poco ms cerca de la
parte superior que en la parte inferior de una pgina. En otras palabras, el tamao ptimo margen es menor
para el margen superior que para el margen inferior (Conover 1985 West 1990).
Texto en el 50% de una pgina 99

Solucin Alrededor del 50% de la pgina debe ser dedicado a texto.

El resto de la pgina se reserva para los espacios en blanco, los encabezados y pies de pgina. Esta es una regla
generalmente aceptada entre los expertos de diseo (Conover 1985, Tinker 1963 West 1990).

Para poner el centro del texto cerca del centro ptico, el texto debe colocarse ms cerca de la parte superior que
en la parte inferior de la pgina. Una proporcin de 2: 3: 4: 5 entre los tamaos de la interior, superior, mrgenes
exteriores e inferior se recomienda a menudo, ya que permite el tamao del margen para aumentar de interior al
principio y exterior a la parte inferior (Gulbins Kahrmann 1992).

50% 50%

Figura 27. 50% texto en una pgina

Algunos documentos no diferencian entre las pginas de la izquierda y pginas de la derecha, por lo que los
mrgenes izquierdo y derecho son del mismo tamao. En este caso, la relacin de margen se puede ajustar a, por
ejemplo, 3: 3: 3: 5. El margen inferior todava debe ser mayor que el margen superior, sin embargo.

Para obtener una geometra de la pgina agradables, tambin se debe tener en cuenta lo siguiente:

Debido a que los encabezados y pies de pgina no forman parte de la zona en vivo de una pgina, que no cuentan
cuando se implementa la regla del 50%.

El margen de canaln mnimo debe ser de 2 cm, para permitir la unin.


100 Diseo y la tipografa

Un rea en vivo cubriendo poco ms del 50% de la pgina es aceptable cuando no la totalidad del rea en vivo
es realmente cubiertos por texto, por ejemplo, debido a la utilizacin de cabezas secundarios que dejan
suficiente espacio en blanco. 6

Una pgina estndar A4 tiene un tamao de 21 29,7 cm. Aqu mrgenes de 2, 3, 4 y 5 cm cumplen la
regla, dejando un rea en directo de 15 21.7 cm. El espacio vivo es
325,5 cm cuadrado, que es 52% de la pgina A4.

tamaos de los mrgenes similares se pueden utilizar para el formato de la carta de Estados Unidos (tamao 21.59 27.94

cm), lo que da un rea en vivo de aproximadamente 15,6 20 cm - un rea de 312 cm cuadrado (52% de la pgina
de carta de nosotros).

Discusin La regla del 50% es de extraar que muchas personas en el primero. Cuando la gente ve una pgina impresa, a
menudo sobreestiman la cantidad de espacio dedicado a la zona en vivo y subestiman la cantidad de espacio
dedicado a los mrgenes. lectores medios estiman que el rea en vivo abarca aproximadamente el 75% de una
pgina, cuando, de hecho, cubre slo el 50% (Tinker, 1963). En otras palabras, el 50% de texto es ms de lo
que parece.

Hay un lmite en el ancho de la lnea que indica que debe haber alrededor Dos alfabetos por lnea, como se muestra
en la Figura 28. Si ms de dos y medio minscula alfabetos fi t en una lnea, la lnea es demasiado ancho. Una
vez que usted tiene de fi ne la zona en vivo de su pgina, usted debe comprobar si una lnea a travs de ella
cumple esta regla, y de otra manera emplear tcnicas para reducir el ancho de lnea. Tener dos columnas por
pgina es una opcin, usando secundarios cabezas es otro, usando un tamao de letra ms grande es de un
tercio.

Para dar a la zona un aspecto regular en vivo e incluso la textura, normalmente no ms de DOS TIPOGRAFAS
debe ser usado, y las lneas deben estar separados por
120% LINEA ESPACIADO.

Dos alfabetos por lnea


Problema Cul es el ancho de la lnea ptima?

Efectivo Al leer, los ojos del lector viajan a lo largo de la lnea de izquierda a derecha. 7 Los ojos hacen pequeos movimientos
espasmdicos, llamados 'movimientos sacdicos', entre los cuales hay perodos llamados 'fijaciones. Fijaciones duran
alrededor de un cuarto de segundo, mientras

6. secundarios cabezas son las partidas que se colocan a la izquierda oa la derecha de los prrafos reales, como se hace en este libro para los
ttulos de segundo nivel.
Dos alfabetos por lnea 101

movimientos sacdicos son slo 0,01 segundos de largo. Es durante las fijaciones que la informacin se recogi
(Crowder 1982).

Un salto de lnea interrumpe el movimiento del ojo a lo largo de la lnea. los ojos del lector tienen que
cambiar de nuevo al principio de la siguiente lnea. lneas cortas aumentan el nmero de saltos de lnea. Si
las lneas son demasiado cortos, los ojos del lector tienen que hallar el comienzo de la siguiente lnea ms a
menudo de lo necesario, lo que rompe el flujo de la lectura y hace tediosa lectura (Conover 1985, Gulbins
Kahrmann
1992).

Por otra parte, las lneas que son demasiado largos tambin hacen la lectura difcil y tedioso. Las lneas largas
hacen que sea di fi culto para los ojos del lector a seguir una lnea y de encontrar el comienzo de la siguiente lnea
una vez que se produce un salto de lnea (Conover 1985, Gulbins Kahrmann 1992).

Por otra parte, el ancho de lnea ptima depende del tamao de fuente y el tipo utilizado. Tipo de establecer en
tamaos ms grandes requiere anchos de lnea ms largas (Conover 1985, Gulbins Kahrmann 1992).

Solucin Aproximadamente dos alfabetos minsculas del tipo de letra estndar deben encajar en una
lnea.

Como regla general, el lmite inferior es alrededor de una hora y media alfabetos minsculas, mientras que el
lmite superior se encuentra cerca de dos y un medio y como mximo tres alfabetos minsculas (Gulbins
Kahrmann 1992).

ABCDEFGHIJKLMNOPQRSTUVWXYZ abcdefghijklmnopqrstuvwxyz

Figura 28. Dos alfabetos por lnea

7. Algunos idiomas no se escriben de izquierda a derecha, pero, por ejemplo, de arriba a abajo. Este patrn y el siguiente no se aplican
a los documentos escritos en estos idiomas.
102 Diseo y la tipografa

Si las lneas son demasiado largos, hay varias maneras de fi x este problema:

Se puede elegir un tamao de letra ms grande.

Usted puede hacer las lneas ms cortas mediante el aumento de los mrgenes.

Usted puede hacer las lneas ms cortas mediante el uso de dos columnas en lugar de uno.

Usted puede hacer las lneas ms cortas mediante el uso de cabezales secundarios.

Discusin Cuando se elige para optimizar el ancho de lnea, ya sea mediante el aumento de los mrgenes
o mediante el uso de dos columnas, usted debe asegurarse de que el diseo de la pgina se ajusta a la TEXTO
EN 50% de una pgina regla.

Justi fi texto ed puede ser problemtico cuando el ancho de lnea se encuentra cerca del lmite inferior. Desde
justificacin requiere que el espaciado entre las palabras (y algunas veces entre los caracteres) puede variar, no
natural pueden ocurrir palabra larga separaciones. Por tanto, es importante utilizar la particin de palabras (West
1990). El uso irregular derecha en lugar de justificacin tambin puede valer la pena considerar.

Tambin hay un efecto sutil que el espaciamiento tiene en la gama de anchos de lnea aceptables. Cuando el
nivel de 120% interlineado se incrementa ligeramente, anchos de lnea un poco por encima de dos y un medio
alfabetos minsculas pueden ser aceptables.

120% Interlineado
Problema Cul es el espaciado de lnea ptima?

Efectivo Una textura uniforme es crucial para la legibilidad de un documento (West 1990). separacin razonable entre las
palabras y las lneas es un requisito previo para una textura uniforme. Mientras que la palabra separacin es en
gran medida determinado por el tipo de letra utilizado, espaciado de lnea no lo es.

Si hay demasiado espacio entre lneas, lneas consecutivas ya no forman una unidad - que debera -
pero en vez parecen estar separados uno de otro. Esto hace que el texto di fi culto a leer (West
1990).

espaciado de lnea, sin embargo, no debe ser demasiado pequea. Para explicar por qu, tenemos que
entender que la lnea de separacin de los resultados de la suma del tamao de letra para el 'lder' - el
espacio real entre las lneas. Una cierta cantidad de conducir es necesario para asegurar que los
ascendentes de una lnea no colisionen con los trazos de la lnea anterior. 8
120% Interlineado 103

Por otra parte, la aparicin de un tipo de letra es influida por su altura x. 9 Un tipo de letra con una
relativamente pequea altura x parece ser ms pequeo que su tamao sugiere, y deja ms espacio
natural entre lneas, reduciendo as la necesidad de dirigir extra.

Solucin La mejor separacin de lneas es aproximadamente 120% del tamao de letra.

En otras palabras, 20% de ataque est normalmente fi ne. Para los tamaos de tipo estndar, tales como

10, 11 o 12 punto esto significa que 2-punto principal es la adecuada.

abcdefgh
klmnoxyz 100% 120%

espaciamiento Figura 29. Lnea

Afortunadamente, la mayora de los procesadores de texto establece el interlineado a aproximadamente 120% como valor por

defecto, y as le proporcionan el espacio derecho alguno tamao de letra que utiliza.

En los siguientes casos, la separacin puede necesitar algo de fi ne-tuning:

Espaciado se puede disminuir para tipos de letra con una relativamente pequea altura x.

Espaciado se puede aumentar para tipos de letra con un relativamente grande x-altura.

El espaciamiento debe aumentarse para lneas largas.

Discusin 120 espaciado% lnea es apropiado para el texto del cuerpo. Encabezamientos, sin embargo, son una excepcin,
ya que se supone que deben hacer que la estructura del texto visible. Para ayudar a los lectores perciben la
estructura de un texto, ttulos deben sobresalir no

8. un ascendente es la carrera de carta que se extiende por encima de la altura x de un carcter en minscula; un descensor es un golpe de una letra

minscula que se extiende por debajo de la altura de la x.

9. La altura de la x es la altura de la letra 'x'.


104 Diseo y la tipografa

solamente por un aumento de tamao tipo, sino tambin por un espaciado de lnea que puede exceder 120%.

La anchura de la lnea ptima se define por la Dos alfabetos POR LNEA patrn. Puede, sin embargo, esta regla
doblar un poco. Si se aumenta la separacin, las lneas que aumentan ligeramente la anchura de lnea
estndar an sern aceptables. Sin embargo, esta tcnica puede ser aplicada solamente en una pequea
parte. Si las lneas contienen significativamente ms de dos y medio alfabetos minsculas, que no son
apropiadas, incluso con mayor espaciado.

dos Tipos de letra

Problema Cuntos tipos de letra son apropiadas y que?

Efectivo Los procesadores de texto a menudo ofrecen una gran variedad de tipos de letra y tamao de letra para elegir
cada vez que los autores desean expresar los diferentes significados de texto puede tener, tales como ttulos,
nfasis, referencias o citas. Sin embargo, cuando se mira a un documento que utiliza muchos tipos de letra
diferentes se dar cuenta de que el documento parece ser catica: el uso de un gran nmero de tipos de letra
es problemtico, tanto por razones estticas como por razones ergonmicas. Por otra parte, el uso de muchos
tipos de letra diferentes es completamente innecesario, ya que las cosas tales como nfasis muy bien pueden
ser expresados con las variaciones tipo.

Pero incluso si nos limitamos a usar slo un pequeo nmero de tipos de letra, cules debemos utilizar?
Tipos de letra pueden expresar cosas tales como la solidez, la formalidad, la innovacin, la moda y as
sucesivamente (Conover, 1985). Por consiguiente, deben ser elegidos de acuerdo con lo que representan.
documentos de proyectos de software no se supone normalmente para expresar la moda o un estilo
'moda' - el requisito principal es que los tipos de letra sean altamente legible. Para este fin es necesario
distinguir entre serif y sans-serif. Los remates son las lneas cortas que atraviesan los extremos de los
trazos de una carta impresa. En lo que se refiere a texto del cuerpo, tipos de letra serif son ms legible
que sansserif tipos de letra, y por lo tanto deben tener preferencia. Sin embargo, las piezas individuales de
texto impresos en una tipografa sans serif se destacan del texto principal y pueden atraer la atencin del
lector (Gulbins Kahrmann 1992).
dos Tipos de letra 105

Solucin En la mayora de los casos, dos tipos de letra por documento son apropiados - un tipo de letra serif para
el texto principal y una tipografa sans serif para los ttulos.

Tambin debe tomar en cuenta lo siguiente:

No hay nada completamente equivocado con el uso de un solo tipo de letra a lo largo de todo el
documento. En este caso un tipo de letra serif debe ser elegido por razones de legibilidad. Sin
embargo, un segundo tipo de letra puede mejorar la apariencia de un documento.

El uso de ms de dos tipos de letra es casi siempre inadecuada. Una posible excepcin es el uso de un
tercer tipo de letra para fragmentos de cdigo incluidos en un documento. El tercer tipo de letra todava
debe utilizarse con moderacin.

El tamao tipo para el texto del cuerpo debe ser de 10 a 12 puntos, mientras que 14 a 18 punto es apropiado para
las partidas, y hasta 24 puntos para ttulos de los captulos y de documentos.

Ejemplo Ejemplo
Aqu Frutiger (12 puntos) es el tipo de letra Aqu Helvetica (12 puntos) es el tipo de letra
sansserif elegido para el ttulo. El cuerpo del texto sansserif elegido para el ttulo. El cuerpo del texto
se imprime en Garamond (11 puntos), que es un se imprime en Times New Roman (11 puntos),
tipo de letra serif. otro serif
tipo de letra.

Figura 30. Diferentes tipos de letra

No hay una regla general que le diga qu tipos de letra que debe utilizar, esto es cuestin de gusto
personal. Los tipos de letra ms tradicionales, como Veces y
Garamond tienden a ofrecer una legibilidad superior a los tipos de letra ms a la moda; Por lo tanto,
parece ms apropiado para la documentacin de los proyectos de software.

Cuando se elige diferentes tipos de letra para el texto del cuerpo y de las partidas, estos tipos de letra no debe
ser demasiado similar, por lo que fcilmente se les puede decir aparte. An as, tienen que encajar juntos en un
sentido esttico. Ejemplos tpicos son Veces y
106 Diseo y la tipografa

Helvetica o Garamond y Frutiger ( Gulbins Kahrmann 1992), como se muestra en la Figura 30.

Discusin Cuando este patrn habla de 'texto del cuerpo', significa texto en los prrafos normales como
as como el texto utilizado en las tablas o diagramas (con excepcin de capturas de pantalla, copias de pizarra, etc.). No
hay necesidad de utilizar diferentes tipos de letra en tablas o diagramas en comparacin con el texto principal.

Tampoco existe una necesidad de expresar nfasis a travs de diferentes tipos de letra. De hecho, es contrario a
la intuicin. Usted puede expresar todo tipo de nfasis necesarios por
El uso cuidadoso de TIPO Variaciones.

El uso cuidadoso de las modificaciones de tipo

Problema Cmo se pueden destacar partes de un texto?

Efectivo Puede utilizar variaciones de tipo de expresar nfasis, referencias cruzadas, etc. Cuando se usa de esta manera,
diferentes variaciones de tipo ayudan a los lectores a entender el texto, y en particular de entender el papel
particular que algunas palabras adquieren. Hay, sin embargo, un inconveniente de la utilizacin de variaciones de
tipo. palabras minsculas normales aparecen en una forma caracterstica definida por las ascendentes y
descendentes de las letras. Una forma caracterstica es crucial para la legibilidad de una palabra. Muchas
variaciones de tipo no disponen de la forma caracterstica tanto como un tipo de letra minscula estndar hace, y
por lo tanto disminuyen la legibilidad. Vamos a echar un vistazo a las diferentes variaciones de tipo de detalle.
Las palabras impresas en cursiva todava tienen una forma caracterstica. No obstante, cursiva disminuyen
ligeramente la legibilidad del texto. Lectura de texto impreso en letra cursiva tarda aproximadamente 4% ms de
tiempo que la lectura del mismo texto impreso en un tipo minsculas estndar (Tinker

1963).

Las letras maysculas no cuentan con una forma caracterstica en absoluto. Disminuyen la legibilidad del texto de
manera espectacular. Leer el texto impreso en letras maysculas requiere alrededor de 12% ms de tiempo que un
texto normal (Tinker, 1963). Por otra parte, 'todas las tapas' no son apreciados por una gran mayora de los
lectores. Adems, todas las tapas de romper el flujo de un texto.

Lo mismo es cierto para los subrayados. Destaca que sola ser una tcnica comn en las mquinas de escribir,
que se dispona de ningn otro elemento de estilo. Pero ambos subrayados y todas las letras maysculas casi
nunca se usan en los libros impresos.
El uso cuidadoso de las modificaciones de tipo 107

Solucin variaciones de tipo pueden ser utilizados para dar nfasis, pero deben usarse con cuidado.

Las siguientes variaciones de tipo se consideran elementos de estilo fi ne (Conover


1985):

Negrita se puede utilizar para resaltar los puntos individuales.

La cursiva se utilizan comnmente para poner nfasis en una palabra en particular.

Versales a menudo se utilizan para representar las referencias cruzadas o nombres de las personas. 10

Todas las letras maysculas y subrayados disminuyen la legibilidad a tal punto que deben ser
evitados por completo.

forma forma FORMA

Figura 31. Formas de diferentes estilos de letra

Discusin Puede utilizar los estilos de fuente especial cuando se organizan como un documento La informacin estructurada. Por
ejemplo, negrita se utiliza a menudo para dejar Thumbnail Sketches
se destacan entre el resto del texto. Cursiva y casquillos pequeos pueden ser tiles para referencias a otros
documentos.

Utilizando subrayados es bastante comn que los hipervnculos en documentos en lnea. Esto puede ser
justificado, pero los documentos impresos son un asunto diferente. Desde este captulo
se trata de documentos impresos, sin embargo, no se recomiendan subrayados.

10. En contraste con todas las tapas, casquillos pequeos tienen claramente una sensacin menos voluminoso, por lo que su uso ocasional est bien. Adems, las

pequeas tapas se pueden ajustar con un capital principal, en cuyo caso se ofrecen algunos forma caracterstica.
108 Diseo y la tipografa

Sentencia cuidado y sombreado


Problema Cmo se pueden separar celdas de la tabla?

Efectivo Los documentos creados en los proyectos de software a menudo incluyen tablas. Para acceder fcilmente a la

informacin en una tabla, los lectores deben ser capaces de reconocer las celdas de la tabla a primera vista. Por otra

parte, el encabezado de la tabla debe ser inmediatamente claro. Hay varias maneras de lograr estos objetivos: el uso de

espacio en blanco, el poder y el sombreado.

El uso de espacio en blanco entre las celdas de la tabla, sin embargo, es problemtica, ya que un poco de espacio en
blanco es necesaria si la separacin de las clulas es a ser clara, en particular cuando las clulas de mesa se
extienden sobre ms de una lnea. Si utiliza un espacio en blanco para separar celdas de la tabla, se pierde el
espacio que de otra manera se podra utilizar para el texto.

Fallo es una tcnica ms eficaz para la separacin de celdas de la tabla. Sin embargo, el fallo es definir slo el tiempo que
las lneas que rodean las celdas de la tabla tienen el espesor adecuado. Las lneas que son demasiado delgadas son
difciles de reconocer, mientras que las lneas que son demasiado gruesas no son estticamente agradables y irritan el
lector. Idealmente, las lneas que separan las celdas de tabla deben tener aproximadamente el mismo espesor que las
letras del tipo de letra seleccionado para el cuerpo del texto.

Por ltimo, el sombreado puede proporcionar estructura a una mesa, pero no debe conducir a un pobre
contraste entre el texto y el fondo.

Solucin Cuidado gobernante y el sombreado conduce a tablas altamente legibles.

Tcnicamente, cuidado fallo y el sombreado significa lo siguiente:

Lneas que rodean celdas de la tabla tienen el espesor correcto si ellos son casi tan grueso como la
letra mayscula I (Gulbins Kahrmann 1992).

Escalas de grises que van del 10% al 20% garantizan un buen contraste y alta legibilidad.

Se pueden combinar ambas tcnicas, por ejemplo mediante el uso de fallo para separar celdas de la tabla y el sombreado
para identificar el encabezado de la tabla.
La colocacin adyacente 109

Tarea Fecha tope

Paquete de trabajo 1 2003-Jul-20

Paquete de trabajo 2 2003-Ago-31

Paquete de trabajo 3 2003-Sep-10

Paquete de trabajo 4 2003-Oct-15

Figura 32. Tabla gobernante y el sombreado

Discusin Obviamente, con cuidado de fallo y el sombreado es til a fin de lograr AMBIGEDADES MESAS, pero en
realidad es aplicable a la presentacin de La informacin estructurada en general. los El uso cuidadoso de variaciones
de tipo puede complementar gobernante y el sombreado, por ejemplo, mediante el uso de negrita en el
encabezado de la tabla.

La colocacin adyacente

Problema Cmo pueden las tablas y diagramas pueden integrar en el texto?

Efectivo La colocacin de tablas y diagramas puede ser difcil. El lugar ideal para una tabla o diagrama est
directamente debajo de la lnea en la que se hace referencia, ya que es donde el primer lector fi ve por ello.
Sin embargo, cuanto mayor sea una tabla o diagrama es, cuanto menor es la probabilidad de que quepan en
el lugar ideal. Puede que no haya suficiente espacio en la pgina.

En lo que se refiere a las tablas, el problema puede ser resuelto permitiendo que los saltos de pgina que se
insertan dentro de una tabla. Esto, sin embargo, no funciona para los diagramas.

La idea obvia es insertar un salto de pgina entre el prrafo y el diagrama si el esquema no encaja en
la pgina actual, lo que hace que el diagrama de aparecer en la pgina siguiente. Esta estrategia, sin
embargo, es definir slo si no hay gran espacio vaco se produce en la parte inferior de la pgina
actual.
110 Diseo y la tipografa

A veces, sin embargo, se produce un gran espacio vaco. Especialmente diagramas grandes pueden
causar pginas medio vacas, lo que es claramente indeseable. En tal caso, necesitamos para
desacoplar el diagrama del prrafo en la que se hace referencia y a la que normalmente sera anclado.
Es posible que tenga que colocar el diagrama en cualquier lugar cerca del punto, quiz ms adelante,
quizs por encima, tal vez en la pgina siguiente.

La consecuencia es que el prrafo no precede inmediatamente el diagrama y otro texto aparece en


el medio. Esto es aceptable, pero requiere que todos los diagramas ser numeradas y ser referidos
por sus nmeros, en lugar de por una expresin como 'el siguiente diagrama'. Lo mismo se aplica a
las tablas si se quieren evitar los saltos de pgina dentro de las tablas.

Incluso la estrategia de desacoplamiento grandes diagramas o tablas en el texto de referencia podra no ser
suficiente. Si un documento contiene un gran nmero de diagramas, puede que no haya suficiente texto para
llenar los huecos dejados por los diagramas.

Solucin Diagramas y tablas estn mejor cerca del texto de la que se hace referencia.

Las siguientes tcnicas pueden ayudarle a poner tablas y diagramas lo ms cerca posible del punto
de referencia como sea posible sin crear vacos incmodos en la pgina:

mesitas y diagramas de frecuencia se pueden integrar en el texto flujo, y aparecen


directamente debajo del punto en el que se hace referencia.

diagramas ms grandes se les debe permitir 'flotar', es decir, deben ser obligados a aparecer en cualquier
lugar cerca del punto desde donde se hace referencia, pero no necesariamente de manera directa por
debajo de ese prrafo. se permite texto para llenar los vacos.

tablas ms grandes, de 4 filas en adelante, deben permitir los saltos de pgina.

Diagramas deben indicar tambin el nmero y deben ser referidos por sus nmeros.

Si hay demasiados esquemas de integracin sin problemas en el flujo de texto, mover al menos
algunos de ellos en un apndice puede ser preferible, ya que esto puede permitir que el texto flujo
permanezca intacto. (Pginas semivaco son mucho ms aceptable en un apndice que en el texto
principal).

Discusin La mayora de los procesadores de texto permiten el uso de marcos anclados en la que un diagrama puede ser
colocado. Tal marco anclado se mueve automticamente con el para-
Pginas coherentes 111

grfico al que est anclado. Los buenos sistemas tambin permiten marcos anclados a ser definida como
flotando, lo que significa que una trama se mantiene cerca del prrafo, pero se pueden colocar en la pgina
siguiente si esto permite un mejor texto de flujo en la pgina actual. Si est disponible, seleccione esta opcin
para grandes diagramas. Permitir saltos de pgina en las tablas hace que la colocacin de mesas ms fcil.
An as, los saltos de pgina en tablas slo se debe permitir siempre y cuando no sacrificar

PGINAS coherente.

Pginas coherentes

Problema Qu opciones existen para evitar la paginacin incmoda que desgarra la informacin relacionada a
pedazos?

Efectivo Los saltos de pgina son una cosa perfectamente normal, sin embargo, algunos saltos de pgina parecen ser aceptable,
mientras que otros no lo hacen. Los saltos de pgina son particularmente incmoda cuando se rompen el flujo
innecesariamente y los lectores de fuerza para saltar hacia atrs y adelante. Este es el caso cada vez que un salto de
pgina hace un pequeo fragmento de informacin aparece en una pgina y material relacionado aparecer en la pgina
siguiente o anterior. Un ejemplo es un encabezado de seccin que aparece en la parte inferior de una pgina, mientras
que el prrafo primero de esa seccin aparece en la pgina siguiente. Otros son 'viuda' o lneas 'hurfanos'. Una viuda
es la ltima lnea de un prrafo que aparece aislada en la parte superior de una pgina, mientras que un hurfano es la
primera lnea de ficcin de un prrafo que aparece aislada en la parte inferior de una pgina.

Tales saltos de pgina son irritantes y pueden hacer que sea di fi culto para los lectores a comprender una idea o lnea de
argumentacin, especialmente para los lectores que navegan un documento rpidamente.

Solucin La lectura de flujo se apoya en las pginas coherentes - pginas que asegurarse de que aparezca un
mnimo de informacin relacionada a cada lado de un salto de pgina.

Se puede lograr mediante el uso de pginas coherentes las siguientes reglas:

No hay encabezados deben aparecer en la parte inferior de una pgina. Un ttulo siempre es seguido
por al menos un prrafo que aparece en la misma pgina.

No hay lneas viudas o hurfanas. Al menos dos lneas de un prrafo deben mantenerse
juntos en cada pgina.
112 Diseo y la tipografa

Las pequeas mesas deben aparecer en una pgina. Si un salto de pgina debe ocurrir dentro de una tabla, se
aplica la regla de la lnea viuda: al menos dos filas de la tabla deben mantenerse juntos en cada pgina.

No hay saltos de pgina dentro de celdas de la tabla.

Discusin Todas estas reglas pueden ser implementadas con procesadores de texto estndar con bastante facilidad. Es necesario
para no permitir lneas viuda y hurfanos para todos los tipos de prrafo y de obligar a todos los tipos de prrafo para los
ttulos que se le mantenga con cualquier prrafo que sigue. Tambin hay que rechazar los saltos de pgina para los
tipos de prrafos utilizados en celdas de la tabla - que por supuesto requiere que los distintos tipos de prrafos pueden
utilizar en celdas de la tabla. Slo los saltos de pgina dentro de las tablas (en lugar de dentro de las clulas de mesa)
pueden requerir intervencin manual.

pginas coherentes pueden adoptar una forma ligeramente diferente en el contexto de ESTRUCTURADO INFORMACIN. Usted
puede decidir no permitir saltos de pgina dentro de los bloques de construccin. Si uno mira hacia atrs en la Figura
12 en la pgina 69, se ve una pgina que consiste en un encabezamiento y cuatro bloques. Tal estructura de pro fi
cios de no ser interrumpidos por saltos de pgina. Sin embargo, si los bloques de construccin se hacen ms
grandes, debe permitir que los saltos de pgina, de lo contrario pginas medio vacas sera la consecuencia - una
contradiccin de tener TEXTO EN 50% de una pgina.

Informes de experiencia
Hay infinidad de ejemplos de los patrones tipogrficos descritos en este captulo. Puede fi nd casos
de estos patrones en casi todos los libros impresos
- los patrones son una prctica comn. Si est interesado en ver una gran variedad de aplicaciones
de estos patrones, un vistazo a un par de libros impresos va a hacer.

Las siguientes cifras, sin embargo, muestran que los patrones tambin se pueden utilizar en la
documentacin del proyecto con facilidad. La figura 33 muestra la pgina que ya sabemos desde el
principio de este captulo, tomado del concepto de uso del Proyecto persistor. La Figura 34 muestra una
pgina del documento de requisitos de Proyecto Contentis. Anotaciones sealan que se han aplicado los
patrones, y cmo. 11

11. No se deje sorprender por la relativamente pequea fuente en estos ejemplos. Los documentos originales eran A4 y tuvo que ser reducido para
ajustarse al tamao de la pgina de este libro. La fuente original hizo permitir la lectura cmoda.
Informes de experiencia 113

buena
- 20 -
paginacin

4.2.1 Adicin de un objeto

addObject ()
razonable
EN OBJECTTYPE : DT DE TIPO uso de
EN Fullkey : DT-KEY
negrita
EN EntryDate : DT-FECHA
EN processNumber : DT-NR

Condiciones previas:

Ninguno

Funcin:

La capa de acceso de datos proporciona una versin inicial de un nuevo objeto de acuerdo el texto, uno
con la fecha de entrada y el nmero de proceso pasado a ella como parmetros. Tras la para el cdigo
inicializacin, el nuevo objeto todava puede ser incompleta; componentes se pueden aadir
sucesivamente. El estado del nuevo objeto est pendiente.

La clave que se pasa a esta funcin como un parmetro de entrada es una clave lgica, que pueden o no
llevar informacin aplicacin especfica. Normalmente es generado por un mdulo especfico fi que todas
las aplicaciones pueden utilizar. En caso de que la tecla fi cado se ha usado previamente para la adicin
de un objeto, se devuelve un cdigo de error.
buena separacin y la

anchura de la lnea
El nmero de proceso es generado por el sistema de gestin de fl ujo de trabajo. Cdigos de retorno: encabezados, uno para

RC-OK El objeto se ha introducido y inicializado correctamente.

RC-KEY La clave lgico especificado no est disponible. buena colocacin


de la tabla
RC-DB La base de datos no est disponible.
RC-PARMETROS La fecha de entrada o el nmero de proceso son ilegales.

de letra para los

4.2.2 Eliminacin de un objeto fallo y el


sombreado
deleteObject () adecuado

EN OBJECTTYPE : DT DE TIPO
EN Fullkey : DT-KEY
EN deletionDate : DT-FECHA
EN processNumber : DT-NR
lo suficientemente blancos

espacio de un tipo

Figura 33. Proyecto persistor: buen diseo y la tipografa


114 Diseo y la tipografa

- 20 -
paginacin

4.2 Boletn de despliegue


La distribucin de un boletn consta de varios pasos que todo ser soportados por el sistema de gestin
de contenido web. Estos pasos son:
un tipo de letra para
1. Meta informacin el texto, uno para los
Meta informacin incluye el boletn de noticias del autor, ttulo, tema y fecha de lanzamiento. El CMS ofrece
ttulos y
una interfaz web para que los usuarios proporcionan esta informacin. Adems, el sistema proporciona el
diagramas
reglas de la
nmero y la fecha de grabacin. Este meta-informacin es necesaria para mejorar las capacidades de
bsqueda.

2. Texto principal

El editor responsable escribe el texto para el boletn de noticias usando el editor Web del sistema de gestin de
contenidos ofrece. herramientas de formato estn disponibles que permiten al editor para elegir tamao y tipo de
letra estilos de fuente.
espaciamiento y
3. Adjuntos
anchura de la lnea de
La mayora de los boletines de noticias vienen con uno o ms archivos adjuntos, como documentos, pginas web, o
encuentro del
presentaciones. El editor agrega estos archivos adjuntos al boletn de noticias utilizando una funcin del sistema de
gestin de contenidos proporciona. Unas buenas

4. Generacin de documentos
Una vez que todos los elementos de la letra de noticias se han reunido, el editor puede hacer clic en un botn, y as
seleccionar la funcin que genera un archivo PDF para el boletn de noticias, y luego invoca el mdulo de flujo de
trabajo para el proceso de revisin.

5. Revisin
El departamento de jefes de recibe un mensaje de que el boletn est listo para su revisin, y
diagrama bien
puede aceptar, modificar o rechazar el boletn. Una vez aceptado, el boletn se copia en el
colocado
entorno de produccin del sistema de gestin de contenidos, y por lo tanto disponible dentro de
la extranet. El siguiente diagrama resume este proceso, y deja claro que el editor es libre de
realizar los pasos 1, 2 y 3 en orden arbitrario.

espacio en blanco

Meta informacion Texto principal Archivos adjuntos dejando


suficiente espacio
para el
Generacin de documentos diagrama

Comentarios

Higo. 5: Proceso de implementacin para boletines cursiva para los

subttulos

Figura 34. Proyecto Contentis: otro ejemplo de diseo y la tipografa


Informes de experiencia 115

A pesar de todos los documentos de ejemplo incluyen casi todos los patrones de este captulo, no tienen
el mismo diseo. Se puede ver que los patrones tipogrficos presentados dejan un amplio margen para la
creatividad - o para el seguimiento de las directrices de diseo que tienen para una organizacin o un
proyecto. Los patrones proporcionan un marco para aumentar la legibilidad y la esttica de los
documentos impresos, pero dejan mucho de su aplicacin abierta. Puede aplicar los patrones tipogrficos
de muchas maneras diferentes y creativas.
4 infraestructura y tcnica
Organizacin

La gestin de la documentacin y gestin de software es esencialmente la misma cosa.

Annimo

Hasta ahora, este libro se ha ocupado de los documentos que necesitamos en nuestros proyectos de
software y lo que debe ser similar. Hemos hablado acerca de su contenido, su estructura y su diseo. Este
captulo se centra en las herramientas y tcnicas que podemos utilizar para obtener dichos documentos ya
ponerlos a disposicin de un equipo de proyecto. Entre otras cosas, los documentos tienen que ser
procesados e impresos, almacenados y recuperados.

En resumen, este captulo nos lleva a la cuestin de lo que la infraestructura de la documentacin debe ser
similar y cmo puede ser organizada. Me gustara empezar con un ejemplo que demuestra por qu es
necesaria la organizacin de la infraestructura de la documentacin. Mira la estructura del sistema fi le ilustra
en la Figura 35, que encontr en un proyecto hace un tiempo. En este proyecto, nadie fue capaz de encontrar
los documentos que estaban buscando. se superponen, no parecen los directorios de documentos
relacionados que se agrupan en directorios, copias de documentos han sido esparcidos en diferentes
directorios y enlaces simblicos completan la confusin. Es un desastre completa - y la figura 35 muestra
simplemente un extracto. Sin embargo, este es un escenario que encontr en un proyecto en el mundo real.

Los miembros del equipo en este proyecto ponen los documentos que haban escrito ms o menos en
cualquier lugar. Ms de una vez que alguien asume un documento no existe, cuando en realidad slo estaba
oculto en el caos. versiones redundantes de docu-
118 Infraestructura y Organizacin Tcnica

Figura 35. documentacin del proyecto mal organizados


119

READERFRIENDLY
CODIGO-COMENTARIO depender de
MEDIA SEPARACIN DE
PROXIMIDAD complemento
PROCESAMIENTO Y

IMPRESIN

puede
requiere depender de
requerir

exigir
rendimientos
NOTIFICACIN EN ACTUALIZAR
CONTENIDO Y

DISEO

plantillas de es una condicin previa


se refiere a los
documentos SEPARACIN DE para
documentos

en el reside en
puede FUENTE simple y
referirse puede ayudar a
mltiple
a mantener la
referirse a los OBJETIVOS DE
documentos documento
en el
horizontal someterse a

puede ayudar a
mantener la
se almacena a
CAMBIOS menudo en IMPORTACIONES

ANOTADOS un POR REFERENCIA

sufre
DOCUMENTO DE
deben ser
ARCHIVO
implementadas con
afecta
puede ser
representada
sufre
por una
puede ser respaldada

con una
POCOS HERRAMIENTAS

REORGANIZACIN A
WIKI
sufre requieren PETICIN

Figura 36. Patrones de infraestructura y organizacin tcnica


120 Infraestructura y Organizacin Tcnica

mentos se mantuvieron, inconsistencias se produjeron y versiones obsoletas eran la fuente de mucha


confusin.

Ciertamente queremos evitar un escenario de este tipo, y yo creo que est claro en este ejemplo que es necesario un
poco de organizacin. Pero la cantidad de organizacin necesitamos? Despus de todo, el exceso de organizacin es
lo contrario de un enfoque gil. Una pregunta de seguimiento se ocupa de herramientas. En qu medida son
herramientas tiles como la medida de lo produccin y mantenimiento de la documentacin se refiere? Hay mucho
valor en las herramientas si hacen nuestro trabajo ms fcil, pero un exceso de nfasis en las herramientas no es gil
tampoco.

Estas preguntas demarcan el rea que los patrones en esta direccin captulo. Los patrones se ocupan de
la organizacin tcnica de todos los documentos producidos en un proyecto, de slo un puado de papeles
cortos a la documentacin completa encontraron en proyectos o proyectos de mayor envergadura con una
criticidad superior. La Figura 36 proporciona una visin general.

Los patrones no pueden proporcionar soluciones prefabricadas para todos los problemas asociados
con la organizacin tcnica de los documentos del proyecto - la documentacin del proyecto pueden
asumir demasiadas formas diferentes para soluciones off-the-shelf a ser posible. En su lugar, estos
patrones se describen los principios que subyacen a un enfoque gil a la creacin y el mantenimiento
de los documentos del proyecto y la gestin de las relaciones entre ellos.

Paisaje documento
Problema Cmo pueden los miembros del equipo tengan una buena visin general de lo que existe en la documentacin de un

proyecto?

Efectivo Documentacin, cuando est mal organizada, en ltima instancia, se producir un error de servir a su
propsito general de hacer la experiencia del proyecto a disposicin de otros miembros del equipo y de los
proyectos futuros. No hay ningn punto en la produccin de documentos si los lectores potenciales no saben
que existen. En un nivel ms tcnico, la organizacin de la documentacin del proyecto debe servir a dos
propsitos: autores entre los miembros del equipo se les debe decir cmo integrar nuevos documentos en la
documentacin existente, y los lectores se les debe decir dnde buscar documentos especficos.

Cmo es una organizacin as como? Con este fin, es til recordar que los documentos de
proyectos a menudo estn conectados por diversos tipos de
Paisaje documento 121

las relaciones, y para examinar cmo los seres humanos organizan los elementos relacionados en sus mentes.

La psicologa cognitiva nos dice que los seres humanos pueden representar conjuntos de elementos relacionados
como imgenes mentales, o paisajes en nuestra mente. En su libro Cmo funciona la mente, Steven Pinker explica
que el cerebro humano est bien entrenado para reconocer objetos por sus formas, y que los objetos complejos
crear un marco de referencia por el cual sus partes pueden ser localizados (Pinker 1997).

Esto sugiere que una buena manera de representar el conjunto de documentos es una especie de paisaje -
pero que? Nosotros no slo imagina este paisaje, pero cuando navegamos la documentacin, que, en cierto
modo, navegar a traves de. Por lo tanto, vamos a echar un vistazo a los hipertextos.

Las experiencias con los hipertextos sugieren que las redes enlazadas son relativamente fciles de seguir si
abarcan un rbol (Botafogo Rivlin Shneiderman 1992) - un rbol representa un equilibrio entre la estructura y la
comprensibilidad. Al parecer, la mayora de los usuarios prefieren un amplio rbol a una estrecha uno: en la
mayora de los casos, una profundidad de 3 es su fi ciente (Horton 1994). Algunos estudios sugieren que los
hipertextos no tienen que ser exactas rboles, como atajos o mltiples puntos de entrada parecen ser fi ne (Furnas
Zacks 1994).

Solucin La documentacin del proyecto se puede representar como una especie de paisaje que los miembros del
equipo pueden utilizar como un mapa mental cuando se recuperan o aadir informacin. Un paisaje
documento que ms o menos se forma un rbol se adapte mejor intuicin humana.

Idealmente, el paisaje documento sigue la estructura del proyecto. La figura 37 muestra un ejemplo. Los
documentos se agrupan si estn estrechamente relacionados. Este paisaje presenta una forma intuitiva de
representar la documentacin del proyecto. No es esttico, sin embargo, pero evoluciona a medida que el
proyecto contina. Hay varias formas en que se pueden implementar un paisaje documento:

La forma ms sencilla es utilizar fi l de directorios y subdirectorios del sistema. Asociar directorios con
temas conduce a una organizacin fcil, pero e fi ciente, siempre y cuando no hay solapamientos
ocasionados por temas ortogonales.

Adems, se puede utilizar un diagrama que visualiza el paisaje documento (como el de la


Figura 37) y que lo incluya diagrama en un documento de introduccin. Ese documento
describe el proyecto y explica lo que existen otros documentos, su propsito y la forma en
que se pueden obtener.
122 Infraestructura y Organizacin Tcnica

Resumen del
sistema

Requisito visin general

especfico catin del diseo

requisitos de
prueba

Casos de prueba
Mdulo
especificaciones

Figura 37. Un paisaje documento

Se puede poner el paisaje de documentos en lnea con hipervnculos actuando como vas de acceso a
los documentos reales, lo que permite a los usuarios viajar en realidad a travs del paisaje documento.

Discusin Qu tcnica se debe preferir? Acecho detrs de esta pregunta es la


deseo de utilizar MEDIA de fcil lectura en la presentacin de informacin. Debido a su alto grado de
referencialidad, el paisaje documento a menudo se presenta mejor en lnea. Si le das a todos los
miembros del equipo de lectura y escritura, el paisaje documento equivale a un proyecto WIKI. Si una
presentacin en lnea es el medio de eleccin depende en ltima instancia del escenario tpico en el
que el
OBJETIVO LECTORES utilizar el paisaje documento. Una cuestin crucial para preguntar aqu es si todos los
miembros del equipo del proyecto tienen acceso a una intranet mediante la cual pueden obtener los
documentos individuales.

Si el paisaje documento es, en efecto puso en lnea, si se ha mejorado con un motor de bsqueda? En grandes
proyectos de esto puede ser vale la pena considerar. La utilidad de un motor de bsqueda est generalmente
limitada, sin embargo, ya que los motores de bsqueda sufren de una solucin de compromiso entre el recuerdo y la
precisin. Recordar y de precisin
Archivo de documentos 123

normalmente sumar el 100 por ciento (Salton 1989) 12: 50 por ciento de recordatorio y 50 por ciento de precisin
pueden ser considerados un resultado tpico (Dumais 1988). Sin embargo, un motor de bsqueda puede resultar
til si un gran nmero de documentos tienen que ser gestionados y la visin general propuesta por el paisaje
documento, sin embargo til, no es totalmente su fi ciente.

Usted puede sentir la importancia de este patrn con una analoga a los documentos individuales. Hemos
visto que la DIRECTRICES PARA LOS LECTORES servir como una hoja de ruta para un documento individual, y de
manera similar un paisaje documento proporciona una manera de acercarse a la documentacin de un
proyecto completo. Por ltimo, el grado de cohesin del documento del paisaje que ofrece informacin sobre
qu tan bien la documentacin del proyecto cumple con el objetivo de presentar La informacin centrada. Si resulta
ser difcil de encontrar una estructura adecuada para el paisaje de documentos, una falta de concentracin
en los documentos individuales puede ser la causa, capaces de dar lugar a AR eorganisation de

el proyecto
documentacin.

Archivo de documentos

Problema Cmo pueden los proyectos de evitar la prdida de cualquiera de las versiones de documentos?

Efectivo Los documentos del proyecto estn organizados tpicamente en un sistema de carpetas y subcarpetas, es de esperar de un
modo bien definido-fi para que los lectores son capaces de recuperar un documento en particular rpidamente.

Sin embargo, muchos documentos se someten a cambio como un proyecto contina. Puede llegar a ser
necesario rastrear la informacin en una versin anterior de un documento. Por lo tanto, a veces no es su fi
ciente para mantener slo las versiones ms recientes de todos los documentos.

An as, los usuarios a menudo prefieren no ver las versiones antiguas de todos los documentos, pero para tener las
versiones antiguas ocultos y tratar con ellos slo cuando realmente necesitan para hacerlo.

12. Recordar describe cmo gran parte de la informacin relevante se encuentra, mientras precisin describe cmo
gran parte de la informacin que se encuentra es relevante. Si una bsqueda produce el 80% de toda la informacin pertinente, a continuacin, slo alrededor

del 20% de los resultados son relevantes - los otros resultados han deslizado simplemente debido a la falta de precisin. Si restringe los parmetros de

bsqueda de modo que el 80% de los resultados son relevantes, la retirada normalmente baja a alrededor del 20% - no se encontr el 80% restante de los

resultados relevantes.
124 Infraestructura y Organizacin Tcnica

Por otra parte, al guardar diferentes versiones de documentos, tenemos que asegurarnos de que no los
confunden. A veces varias personas contribuyen a un documento, por lo que necesitamos un mecanismo
que impide que estas personas trabajen en la misma versin, al mismo tiempo, anulando el trabajo del
otro. Por ltimo, hay que tener en cuenta que los problemas tcnicos, tales como accidentes de disco duro
pueden conducir a la documentacin del proyecto estn perdiendo. Esto suena trivial, pero mucho dao ya
est hecho, arruinando el trabajo de semanas o meses, por un fallo de hardware.

Solucin documentacin de proyecto de archivo ofrece la ventaja de que las versiones se pueden recuperar
cuando sea necesario.

Un archivo de documentos 13 pueden tener diferentes grados de sofisticacin.

La forma ms simple de archivo consiste en una convencin de nomenclatura para las versiones de
documentos antiguos, que no se eliminan, sino que permanecen en el sistema de archivo, junto con un
servicio de apoyo central que cubre toda la documentacin del proyecto.

Un sistema de gestin de con fi guracin ofrece ms funciones. Permite a los usuarios comprobar in y
check out documentos. Un mecanismo de bloqueo se asegura de que los cambios en un documento se
pueden hacer solamente por la persona que haya comprobado hacia fuera. El sistema almacena
automticamente versiones antiguas y las recupera a peticin (Berczuk Appelton 2003).

Como tenemos la intencin de utilizar las herramientas ms sencillas que ful fi l nuestros propsitos, la idea de control de

versiones basadas fi sistema de ficheros tiene un gran atractivo, ya que no requiere herramientas adicionales, a pesar del

hecho de que no hace que las versiones antiguas invisible. Sin embargo, muchos proyectos utilizan un sistema de gestin

con fi guracin de todos modos, en especial para el cdigo fuente. En este caso, la segunda opcin no representa un

esfuerzo adicional y est bien vale la pena considerar. Un sistema de gestin de configuracin bastante simple con fi suele

ser el caso, ya que los sistemas complejos requieren un esfuerzo de aprendizaje que es raramente justificado.

Discusin La creacin de una documento horizontal establece una estructura en forma de rbol. Un archivo es una forma de
implementar un paisaje. Puede documentos relacionados con el grupo

13. Un archivo aqu se refiere a cualquier mecanismo utilizado para hacer un seguimiento de las versiones. A diferencia de un Entretanto ms estrecha

ing del trmino, el archivo no implica necesariamente que las versiones antiguas pueden mover a los medios de almacenamiento fuera de lnea para fines tales

como liberando espacio.


wiki 125

en carpetas y, posiblemente, subcarpetas, ya sea en el sistema fi le o en un sistema de gestin de configuracin


con fi.

wiki
Problema Cmo puede la documentacin se dar una ventaja ms interactivo?

Efectivo Documentacin tiene mucho a su favor, a largo plazo y amplia disponibilidad, entre otras cosas. Sin
embargo, la interaccin es importante en un equipo de colaboracin. La gente tiene preguntas o le
gustara dar respuestas. Se ha dicho muchas veces antes: la documentacin y la interaccin no se
oponen entre s, sino que se complementan entre s.

Por ejemplo, es posible que tenga una pregunta acerca de un documento mientras su autor est de
licencia. Tal vez otra persona tambin sabe la respuesta, pero no se sabe quin podra ser esa
persona.

Con este fin, el apoyo tcnico para la combinacin de la documentacin y la interaccin podra ser
til. Lo que podra apoyar parecerse? Su objetivo debe ser aumentar la interaccin entre el equipo,
sino que tambin debe tener en cuenta que podra ser necesaria una comunicacin asncrona.

Solucin Un Wiki ofrece acceso a la documentacin del proyecto a travs de un servidor de intranet, y,
adems, permite al equipo para publicar notas y mensajes a otros segn sea necesario.

Un Wiki es esencialmente un sitio web en el que todos los miembros del equipo han de lectura y escritura. 14

Como miembro del equipo, puede utilizar un Wiki de varias maneras:

Puede agregar documentos o nuevas versiones de los documentos.

Puede descargar los documentos que necesita.

Puede dejar mensajes a otros con nuevas ideas o preguntas que pueda tener.

Puede responder a los mensajes de los dems.

14. 'Wiki' es la palabra hawaiana para 'rpido'. El trmino 'Wiki Web' se introdujo por Ward Cunningham para sitios web de colaboracin
que dan a sus usuarios de rpida lectura y escritura (Leuf Cunningham 2001).
126 Infraestructura y Organizacin Tcnica

En otras palabras, un Wiki es un foro de comunicacin asncrona sin embargo colaboracin


interactiva.

Discusin Un Wiki implementa el proyecto de documento horizontal y permite a los miembros del equipo para navegar a travs
de l. Un Wiki no proporciona la seguridad con respecto a versiones de que una DOCUMENTO DE ARCHIVO hace.
Sin embargo, se puede instalar un contenedor en el back-end de la Wiki para cuidar de las cosas tales como el
control de versiones y de respaldo.

Los wikis son bien conocidos para no imponer ninguna restriccin de acceso a escritura en sus usuarios: todo el mundo
puede cambiar nada. Esto puede parecer un poco arriesgado cuando un grupo grande y el anonimato de las personas
tienen acceso, aunque las experiencias son positivas, y para estar en el lado seguro, usted todava puede hacer copias
de seguridad. Un equipo de proyecto, sin embargo, no es una masa annima, y el acceso general para todo el mundo no
debera representar un problema. Sin embargo, la mayora de los documentos del proyecto tienen

UNO Autor responsable, y los miembros del equipo se les puede pedir que consultar con la persona que est
a cargo de un documento antes de hacer cambios en l. Porque un proyecto Wiki ofrece un mayor grado
de interaccin que un simple archivo no, el establecimiento de un Wiki que pone en su camino hacia una INFORMACIN
MERCADO en la que los documentos se ofrecen e intercambian de forma activa.

Cdigo-comentario de proximidad

Problema Cul es una manera fcil de mantener la documentacin que hace referencia al cdigo real?

Efectivo La documentacin puede tomar diferentes formas. En primer lugar, la documentacin consta de los
documentos que se producen en un proyecto. En segundo lugar, la documentacin cubre los comentarios
que los programadores ponen en el cdigo fuente, que no deben ser ignorados. La pregunta aqu es, que tipo
de documentacin deberamos preferir?

Una cierta proximidad de cdigo y los comentarios que se refieren a que ofrece varias ventajas. En primer
lugar, los programadores, cuando se ven en un programa, no tienen que buscar el comentario til en otros
lugares.

En segundo lugar, comentarios de cdigo fuente son relativamente fciles de mantener. Si cambia algo
en un programa y su documentacin se encuentra en otro lugar, lo ms probable es que se olvide de
cambiar la documentacin correspondiente.
Cdigo-comentario de proximidad 127

Las actualizaciones son mucho ms fcil si todo lo que necesita hacer es actualizar algunos comentarios en el cdigo.

Programacin literaria va un paso ms all. Programacin literaria denota un estilo de programacin que fue
presentada por Donald Knuth. Sugiri que los programas deben ser escritos de una manera que se explica a
otros seres humanos lo que se supone que el ordenador haga Knuth (1992). La cuidadosa seleccin de los
nombres de las variables es particularmente importante. Lo ideal sera que un programa se convierte en un texto
que no necesita ms comentarios.

Pero, es siempre posible? No todos los temas que requiere la documentacin est directamente relacionada
con el cdigo. Hay temas de nivel superior, tales como las necesidades del usuario o la arquitectura de software
que no pueden ser relacionados con las lneas individuales de cdigo y que son, por tanto, ms all de lo que
puede ser documentada dentro de un programa.

Solucin Documentacin del cdigo, en la medida en que un equipo de proyecto considera necesario, es
mejor hacerlo a travs de comentarios de cdigo fuente. documentos separados deben
reservarse para problemas de nivel superior, tales como resmenes, requisitos, diseo y
arquitectura.

Las siguientes pautas le ayudarn a hacer comentarios de cdigo tan simple como sea posible.

Mantener el software lo ms claro posible, por ejemplo a travs de nombres bien elegidos para
objetos y funciones.

Aadir comentarios slo cuando el cdigo sola no proporciona suficiente informacin, y guardan
las observaciones cerca del cdigo al que se refieren. La proximidad de cdigo y los comentarios
correspondientes hace que los comentarios relativamente fciles de mantener. Cada vez que se cambia
el cdigo, usted tiene los comentarios correspondientes justo en frente de usted y usted puede cambiar
en consecuencia. Las actualizaciones de documentos slo sern necesarias cuando los cambios
afectan a algo ms que el cdigo, tales como el diseo general.

Discusin Este patrn ya se toca el tema de la MEDIA de fcil lectura. Ese patrn se centra en la cuestin de la
eleccin de los medios para los documentos del proyecto, pero esa pregunta es razonable slo si
estamos seguros de que un documento es el medio adecuado en absoluto. El patrn actual seala
que cierta informacin puede no ser necesario un documento, y que la informacin est mejor
conservado dentro del programa.
128 Infraestructura y Organizacin Tcnica

De fcil lectura-Medios

Problema Qu es ms apropiado: los documentos destinados a ser utilizados en lnea o documentos destinados
a la impresin?

Efectivo Por razones ergonmicas, la mayora de las personas prefieren leer documentos en papel en lugar de
documentos en lnea. Esto es cierto en particular para los documentos ms largos que los lectores pueden
dedicar ms tiempo a la lectura. Los documentos impresos ofrecen una mejor resolucin y contraste de una
pantalla de ordenador, documentos impresos no necesitan una fuente de alimentacin elctrica, y los lectores
pueden tomar los documentos impresos con ellos sin tener que llevar un ordenador alrededor (Hsu Mitchell
1997). Los documentos impresos pueden ser fcilmente marcados por hacer comentarios editoriales. En
resumen, papel permite que los lectores se sientan, descansar y se concentran. Existe un debate en curso
acerca de si los documentos impresos y libros con el tiempo sern reemplazados por versiones electrnicas.
Hay avances tecnolgicos en lo que se refiere a la ergonoma de los documentos electrnicos (Press 2000).
Pero, por el momento, la mayora de la gente prefiere documentos impresos para la lectura.

Sin embargo, algunos documentos del proyecto se caracterizan por un alto grado de referencialidad. No
puede haber referencias cruzadas dentro de los documentos, as como referencias a otros documentos. Slo
documentos electrnicos ofrecen mecanismos tales como enlaces de navegacin que hacen de tales
referencias fcil. Los lectores tienen que utilizar documentos en lnea si desean utilizar tales caractersticas
(Hsu Mitchell
1997).

Por otra parte, las presentaciones en lnea pueden permitir a los lectores a jugar un papel ms activo. En un
escenario avanzado, los lectores pueden participar si la documentacin incluye una simulacin o una animacin,
aunque esto es bastante poco comn para la documentacin de los proyectos de software normales.

Hay dos argumentos ms que parecen sugerir una ventaja que los documentos en lnea tienen sobre los
documentos impresos. Ni el argumento es vlido, pero ambos deben mencionarse para mayor claridad.

En primer lugar, puede sonar interesante presentar los documentos rpidamente cambiantes en lnea, con la esperanza de
que los lectores leen automticamente las versiones ms recientes. Es una buena idea - pero no funciona. Cuando la gente
encontramos que tienen que leer un documento de este tipo, que con frecuencia se imprimen, aunque no estaba destinado
para la impresin en el primer lugar fi, por lo que no se dan cuenta cuando hay una actualizacin disponible en lnea.
De fcil lectura-Medios 129

En segundo lugar, el uso de motores de bsqueda se utiliza a veces como un argumento para documentos
electrnicos, pero esto no es un argumento vlido tampoco. La aplicacin de un motor de bsqueda de un
documento requiere que el documento estar disponible electrnicamente, sin embargo, no tiene nada que ver
con el medio en el que est dirigido el documento: documentos que se van a imprimir se puede analizar tan bien
como documentos en lnea puede .

Solucin La eleccin de un medio debe reflejar el uso tpico de un documento. La regla de oro es:
impresin es buena para la lectura, en lnea es bueno para mirar las cosas.

Las siguientes pautas pueden ayudar a tomar la decisin.

Algunos documentos se suelen leerse, en lugar de ser navegado, al menos en algunas partes. Los
miembros del equipo pueden sentarse y concentrarse en las partes en las que estn interesados. Tal
vez van a tomar el documento casa o en un viaje de negocios. Estos documentos deben ser
proporcionados en un formato que permita imprimir.

Algunos documentos se utilizan de una manera que en realidad no puede ser referido como 'lectura'. Ms
bien, la gente toma un breve vistazo a esos documentos, o navegar a travs de ellos, a menudo durante la
programacin o el diseo, por lo general el gasto slo un corto perodo de tiempo en ellos. Tales
documentos se presentan mejor en lnea.

La siguiente tabla resume qu medio est normalmente el ms adecuado para varios tipos de
documentos.

Impresin En lnea

Viabilidad del concepto de estudio o Descripcin de la arquitectura del

documento de estrategia de arquitectura paisaje documento API descripcin

visin general espec fi cacin de en esta gua del usuario Ayuda en

documentos Diseo Resumen concepto lnea On-line Glosario de simulacin

de uso Gestin Glosario


130 Infraestructura y Organizacin Tcnica

Como muestra la tabla, no hay una clara separacin entre los documentos que se presentan como
la mejor impresin y los que se presentan mejor en la lnea. El panorama arquitectnico aparece en
la impresin y en lnea, como es el glosario.

Entonces, qu es en ltima instancia el medio 'derecho'? La verdad es que hay documentos que algunos
lectores prefieren imprimir que otros prefieren usar en la lnea, y todos tienen razones de su eleccin. Esto
sucede con los documentos que algunos lectores leer de principio a fin, pero que otros utilizan para buscar
informacin y referencias para los siguientes. En este caso satisfacer las necesidades de los lectores
requiere que se proporcione ambos una versin imprimible y una versin en lnea.

Discusin Si un documento es necesario tanto en papel como en lnea, a veces es tentador para configurar el documento
para su uso en lnea y utilizar la misma versin para imprimir. Adems de la reduccin del esfuerzo, esto tiene la
ventaja de que la informacin no se mantiene de forma redundante en dos documentos. Sin embargo, esto no
es una buena idea. Los documentos que no tengan el formato correcto no se imprimen muy bien. Uso de
documentos en lnea para la impresin debe ser evitado por razones ergonmicas. Es una idea mucho mejor
para generar la versin en lnea de forma automtica - una caracterstica que muchos procesadores de texto
ofrecen, y que evita la redundancia. La generacin de documentos en lnea de forma automtica no slo es til
cuando se requiere tanto una impresin de una versin en lnea. Tpicos documentos en lnea - los que no se
lee, pero slo navegar a travs de, los que tienen muchas referencias - a menudo pueden ser extrados de otras
fuentes. Por ejemplo, una descripcin API a menudo se puede obtener de comentarios de cdigo fuente. La
generacin de documentos en lnea es una buena idea siempre que sea posible, ya que evita inconsistencias
manteniendo una FUENTE NICA Y OBJETIVOS DE MLTIPLES.

La decisin sobre los medios de comunicacin por lo general no se limita a los documentos individuales, sino que se
extiende a todos los documentos de un tipo particular, al menos dentro de un proyecto. Usted decide sobre el medio
para todas las especificaciones, por ejemplo, en lugar de para un solo espec fi cacin. La decisin, por lo tanto
fuertemente influye en la definicin de
DOCUMENTO PLANTILLAS que forman la base para varios documentos del mismo tipo.

Diferentes medios colocan diferentes requisitos de diseo y formato. Los documentos que se van a
imprimir deben seguir las directrices que se presentan en el Captulo 3 de Diseo y la tipografa. Estas
directrices, sin embargo, no necesariamente se aplican a documentos en lnea.
Separacin de Contenido y disposicin 131

Por lo que en lnea se refiere a la documentacin, las pautas a seguir son esencialmente los indicados
en la literatura para la organizacin de los sitios Web. Puesto que este libro tiene su foco principal en
documentos impresos, tales directrices estn fuera de su alcance, pero la literatura ofrece un montn
de fuentes. Un ejemplo es el libro de Jakob Nielsen Usabilidad Web Proyectos ( Nielsen 2000), otro es el
libro de William Horton El diseo y la documentacin en lnea de escritura ( Horton

1994). Documentacin en lnea tambin est sujeto a los patrones: Robert Orenstein ha publicado una Lengua
del patrn para un sitio Web de Ensayo-base ( Orenstein
1996). Entre otras cosas, se recomienda De poca profundidad rboles de documentos y un Seccin
introductoria con un Imagen de introduccin.

Separacin de Contenido y disposicin


Problema Cmo pueden los diseos de documentos de texto pueden modificar y volver a utilizar fcilmente?

Efectivo El diseo de un documento puede tener que cambiar. En primer lugar, es posible que tenga que adaptar el
diseo para cumplir con alguna norma, tal vez siguiendo directrices especficas, tal vez siguiendo la peticin de
un cliente. En segundo lugar, y ms probable, es posible que tenga que soportar un canal de salida adicional: tal
vez un documento de impresin debe estar disponible para su uso en lnea tambin.

Pasando por todos los prrafos de un documento que acaba de cambiar su apariencia es un
trabajo tedioso, y uno inaceptable. Tenemos que realizar un cambio, al menor costo posible. Ya
sea que se realice el cambio de diseo de forma manual, o si una herramienta est disponible,
cambios en el diseo, no vuelva a ser actividades de alto coste.

Por otra parte, una vez que un buen diseo ha sido diseado, queremos ser capaces de volver a utilizarlo para
otros documentos tambin. Cmo podemos hacer eso? Si echamos un vistazo a los sistemas de gestin de
contenidos, podemos ver lo que una posible solucin podra ser similar. sistemas de gestin de contenidos
desacoplan contenidos y diseo: graban el contenido sin formatear, por un lado, y por otro proporcionan
mecanismos de fi ne estilos de diseo. El grado de sofisticacin que se encuentra en los sistemas de gestin
de contenidos es innecesario para los documentos de proyectos ordinarios, pero los indicios principio
subyacente en una direccin que puede tomar.
132 Infraestructura y Organizacin Tcnica

Solucin estilos de diseo pueden ser de fi nido y se asigna a porciones de contenido. Estos estilos de diseo se
pueden cambiar fcilmente y se pueden reutilizar a travs de los documentos.

El uso de un tpico procesador de textos, la separacin de contenido y el diseo se puede implementar muy
fcilmente de la siguiente manera:

Definen los tipos de prrafo adicional en su documento.

Asignar un formato a cada tipo de prrafo.

Asignar un tipo de prrafo para cada prrafo, y as determinar la disposicin de ese prrafo.

Evitar cualquier anulacin del formato de un prrafo que ha sido asignada por su tipo.

Esta aplicacin se ilustra en la Figura 38.

Otra opcin, aunque menos comn, es utilizar XML para estructurar el contenido de un documento, y para
usar XSLT para asignar los formatos XML para los bloques individuales. O bien, podra escribir
documentos en HTML, y proporcionar el formato a travs de las hojas de estilo (CSS).

En cualquier caso, el cambio de la definicin del trazado afecta a todo el documento en consonancia,
siempre que se utilice el estilo de diseo en particular. La reutilizacin de los estilos de diseo en otros
documentos no es un problema.

Discusin Este patrn es la condicin previa para otros dos patrones. En primer lugar, sin una separacin de
contenido o de presentacin plantillas de documentos no sera posible. Tales plantillas definen independientes
del contenido de formato que se reutiliza en todos los documentos que se derivan de ellos.

En segundo lugar, a veces podemos generar documentos de forma automtica, lo que nos da una FUENTE
NICA Y OBJETIVOS DE MLTIPLES. un mecanismo de este tipo se utiliza a menudo para asignar un formato
diferente para el mismo contenido, por ejemplo para generar cdigo HTML de texto bien formateado. Tal
mecanismo no poda llevarse a cabo sin la separacin de contenido y el diseo.

Cuando se utiliza un procesador de textos, es probable que encontramos la separacin de contenido y el


diseo a ser un poco difcil si lo siguen hasta el ltimo detalle. De hecho, incluso los expertos de
autoedicin han sido vistos sin obedecer la disposicin del prrafo vez en cuando, cuando sentan la
definicin de un texto de prrafo extra no estaba justificado. Esto es aceptable siempre y cuando sea una
excepcin, y siempre y cuando usted sabe que usted est negociando flexibilidad de diseo fl de
Fuente nica y Objetivos Mltiples 133

Sans-serif 14point, negrita, sin


Solucin Ttulo
sangra
estilos de diseo pueden ser de fi
nido y se asigna a porciones de
contenido.
bala
En un procesador de texto, esto significa:

sangra
De fi ne los tipos de prrafos 11point serif, sin
Bloquear
sangra
bala serif 11point, negrita, sin
Asignar formatos a estos tipos

11point serif, la sangra, una


Asignar un tipo a cada miniatura de
prrafo

Evitar las anulaciones

Figura 38. Separacin de los contenidos y el diseo como realizadas por un procesador de textos

conveniencia momentnea. En ltima instancia, las anulaciones rompen el concepto de DOCUMENTO PLANTILLAS
y Sacrificio sus ventajas. Ya sea una separacin limitada de contenidos y el diseo es justificado o no
depende de la probabilidad y la frecuencia con la que es probable que tengan que reaccionar a las
solicitudes de cambios de diseo.

Fuente nica y Objetivos Mltiples


Problema Cmo pueden los mltiples puntos de vista de un documento pueden crear sin duplicar el mantenimiento?

Efectivo A veces el mismo documento debe aparecer en diferentes formatos. Por ejemplo, podemos
requerir tanto una versin imprimible y una versin HTML de una
134 Infraestructura y Organizacin Tcnica

documento. La preparacin de un documento separado de formato, sin embargo, conduce a redundante


documentos.

O considerar los comentarios en el cdigo fuente que describen, por ejemplo, interfaces de clase en un lado y una
descripcin de la API HTML en el otro. Tal vez no pueden, o no quieren, Sacrificio tampoco. Una vez ms, la
redundancia se produce.

Podemos ver en estos escenarios que la informacin redundante, no siempre se puede evitar.

Redundancia, sin embargo, crea numerosos problemas - esto es tan cierto para la documentacin, ya que es
para el software. Cuando la informacin se almacena de forma redundante en varios lugares, mantenimiento
documento se convierte en caro y propenso a errores. Los cambios tienen que hacerse varias veces e
inconsistencias ocurren fcilmente. Esto no es lo que nos proponemos - claro que no queremos mantener
documentos redundantes y de forma manual mantenerlos constantes.

Afortunadamente, hay maneras de lidiar con la redundancia. La idea clave es entender que todo lo que
necesitamos son varias vistas de la misma informacin, y que no hay necesidad de mantener ms de
un original.

Solucin La infraestructura de la documentacin puede emplear mecanismos que tienen documentos de


origen y generan automticamente vistas adicionales. Tales mecanismos evitar la doble
mantenimiento y garantizar la coherencia.

Si bien esta tcnica no evita la redundancia, no administrarlo: slo el documento de origen tiene
que ser mantenido. Los siguientes mecanismos son ejemplos destacados:

La mayora de los procesadores de texto son capaces de exportar HTML, como se ilustra en la Figura 39.

Herramientas tales como JavaDoc del Kit de desarrolladores de Java (Flanagan, 2002) permite HTML
que se genera a partir de los comentarios de cdigo fuente. Una cuestin interesante sigue siendo: si
necesita varias vistas de un documento, que debe ser la fuente y cules deberan ser los objetivos? Un
mecanismo para generar un punto de vista especfico slo puede bajar de la estructura en el camino, as que
las vistas que ofrece el ms alto grado de estructura debe ser siempre la fuente. Por ejemplo, un documento
bien estructurado
es inherentemente ms
profundamente estructurado que un documento HTML, por lo que es aconsejable utilizar el documento como la
fuente y HTML como el formato de destino. Como consecuencia, si
Fuente nica y Objetivos Mltiples 135

Figura 39. Un documento HTML generado a partir de un documento de texto

sabe que necesita tanto el texto como HTML, siempre mantener el texto y generar el cdigo HTML.

Del mismo modo, como comentarios de cdigo fuente se asocian con las lneas de cdigo, y por lo
tanto ofrecer un mayor grado de estructura de HTML, comentarios de cdigo fuente se extraen del
cdigo y en HTML, y no viceversa.

Discusin generacin automtica de documentos no cambia la estructura de un documento, simplemente el formato del
documento o de su diseo: el contenido permanece intacto. La condicin previa para que esto funcione es
que el contenido y el diseo no se mezclan en un documento, pero se separan correctamente. Por lo tanto, la
viabilidad de la generacin automtica de documentos depende de la SEPARACIN DE CONTENIDO y el diseo

principio que se adopta para el documento de origen.

Los mecanismos para la generacin de documentos a menudo tienen que asumir que las fuentes estn
disponibles en un determinado lugar en el DOCUMENTO DE ARCHIVO. Por tanto, una estructura de archivo estable es
la condicin previa para este patrn para ser til. Esto se puede lograr por lo permite REORGANIZACIN A PETICIN solamente.
136 Infraestructura y Organizacin Tcnica

Importacin por referencia

Problema Cmo pueden los diferentes documentos utilizar el mismo diagrama o tabla consistente?

Efectivo La informacin contenida en diagramas, dibujos y tablas a veces es til en el contexto de varios
documentos. Por ejemplo, un diagrama que describe la arquitectura de software puede resultar til en
una Introduccin a la arquitectura, un documento de diseo y un concepto de uso.

Si incluimos estos elementos de informacin en varios documentos, estos elementos aparecen de forma
redundante, trayendo consigo los problemas conocidos de la redundancia: doble mantenimiento, posibles
inconsistencias y as sucesivamente. Sin embargo, la generacin de documentos en los que aparecen estos
elementos no es una solucin, ya que no es los documentos completos que son redundantes, slo pequeos
objetos en su interior.

An as, no hay necesidad de almacenar dichas piezas de informacin redundante. Todo lo que necesitamos son
mltiples representaciones de la misma informacin.

Solucin Artefactos que deben aparecer en mltiples contextos pueden ser importados por referencia en
los documentos que los incluyen.

Figura 40. Un grfico referenciado por dos documentos


Importacin por referencia 137

Esta tcnica se ilustra en la Figura 40, y se puede caracterizar como sigue:

Los diagramas, imgenes, tablas, etc. se almacenan en lugares apropiados.

Se incluyen en todos los documentos donde sea necesario el uso de la 'importacin por referencia'
mecanismo que la mayora de los procesadores de texto ofrecen.

Si se cambia el elemento original, todas las instancias dentro de esos documentos se actualizan
automticamente la prxima vez que se abran los documentos.

Discusin Esta tcnica evita los problemas de mantenimiento asociados con la redundancia. Sin embargo, no
se puede negar que hay varios inconvenientes asociados con la importacin por referencia, lo que
usted tiene que sopesar contra sus ventajas si tenemos en cuenta usarlo.

En primer lugar, si se refiere al artefacto con el texto, ese texto no se actualiza automticamente
cuando cambia el artefacto, lo que conlleva el peligro de conflictivos informacin en el diagrama o
tabla en una mano y el texto que lo rodea por el otro.

A continuacin, si se necesitan artefactos espec fi cas en varios documentos, estos documentos se solapan, al
menos hasta cierto punto. Esto puede ser una indicacin de que dichos documentos no se enfocan correctamente,
aunque no necesariamente. Si esto es el caso, se puede tratar de evitar la situacin por completo mediante la
consecucin de ms La informacin centrada, resultando en solapamientos ms pequeas.

Otra desventaja es que un documento que hace referencia a los objetos externos requiere varios archivos, por lo que
la apertura de un documento, puede tardar ms tiempo de lo que debera. Por otra parte, el uso de muchos artefactos
que se hace referencia dentro de un documento es a menudo una construccin bastante frgil, como el DOCUMENTO DE
ARCHIVO en la que los elementos se almacenan podra someterse a una reorganizacin. Esto ayuda a poner en
prctica aqu REORGANIZACIN A PETICIN solamente, es decir, slo para reorganizar el archivo cuando se solicita
activamente por sus usuarios. Sin embargo, el mantenimiento de los documentos con referencias a elementos de
informacin puede ser incmodo. Para solucionar el ltimo problema, puede considerar la importacin de artefactos en
funcin, nicamente, siempre y cuando aplica su principal ventaja: el uso de importacin por referencia, mientras que
los artefactos son susceptibles de cambiar con frecuencia, y sustituir las referencias de copias importadas cuando los
cambios se convierten en un mantenimiento menos probable y separada ya no aparece una carga.
138 Infraestructura y Organizacin Tcnica

La separacin de procesamiento e impresin


Problema Cmo pueden producir proyectos de documentos tiles, imprimibles?

Efectivo Los miembros del equipo deben ser capaces de leer e imprimir documentos de cada uno, si se utilizan las
mismas herramientas o no, e independientemente de la plataforma en la que se produjeron los documentos.
Por otra parte, los clientes y los miembros de otros equipos que tienen acceso a la documentacin del
proyecto tambin deben ser capaces de leer e imprimirlo.

Sin embargo, otras personas no se supone a veces modificar la documentacin, por lo que debe ser una
forma de proporcionar una versin del documento que no permite el posterior procesamiento.

Adems, un documento debe ser la misma donde quiera que se imprime. Cuando se entrega un
documento, los lectores no deben ser capaces de anular el diseo y formato, ni deben el diseo y
formato ser anulado por cierto, por ejemplo, la impresora Con fi guracin.

Por desgracia, algunos procesadores de texto cambian documentos de forma automtica el momento en que se
abren. Peor an, las macros, instalaciones de fuente y configuraciones de impresora fi permitir que los documentos se
ven diferentes en diferentes sistemas. Bajo estas circunstancias, el uso de elementos de formato, incluso simples,
tales como los saltos de pgina se convierte en una cuestin de pura casualidad.

Adems, la apertura de un documento puede ser peligroso cuando el documento contiene macros que se
ejecutan automticamente, como macros pueden albergar virus. Preferiblemente, no hay macros deben ser
ejecutados al leer o imprimir un documento.

Solucin Si un equipo elige para entregar la documentacin del proyecto en un formato de impresin que est ampliamente
disponible, todos los lectores son capaces de imprimir los documentos, independientemente de la plataforma que
utilizan.

La clave de esta solucin es la clara separacin de formatos para el procesamiento de un documento en una
mano y formatos de impresin en el otro. Los equipos deben tener cuidado para distribuir nicamente versiones
de sus documentos en el formato de impresin siempre que no se espera que los receptores para procesar los
documentos ms.
plantillas de documentos 139

En detalle, los formatos de impresin deben cumplir con los siguientes requisitos:

formatos de impresin deben captar al mximo toda la informacin sobre el diseo y el formato de
un documento. Esto incluye el uso de tipos de letra, la geometra de la pgina y as sucesivamente.
El diseo de pgina del documento impreso debe ser parte del documento solo, y no debe
depender de la infraestructura circundante.

formatos de impresin no deben permitir su posterior procesamiento.

Idealmente, formatos de impresin no deben permitir la ejecucin de macro tampoco.

Para asegurar la documentacin est ampliamente disponible, el acceso a los formatos de impresin debe estar libre.

Discusin El PDF de descripcin de pginas (formato de documento porttil) es el ejemplo ms destacado de un


formato de impresin que describe por completo y de forma inequvoca la pgina impresa. PDF es una
excelente opcin, ya que se puede leer con Adobe Acrobat Reader, una herramienta que est libremente
disponible para mltiples plataformas.

PostScript es otro formato de impresin til, ya que se puede leer con GhostView - otra herramienta gratuita. Sin
embargo, PostScript se usa con menos frecuencia, y no como independiente de la plataforma como PDF.

Obviamente, el uso de un formato de impresin tiene una influencia en la eleccin de un instrumento de


documentacin. Si usted es responsable de la creacin de la infraestructura de la documentacin, es posible que
desee dar preferencia a las herramientas que directamente
soportar los formatos de impresin, por ejemplo, herramientas que generan PDF. Tenga en cuenta, sin embargo, que ALGUNOS
INSTRUMENTOS debe ser su fi ciente para fines de documentacin.

plantillas de documentos
Problema Cmo pueden todos los documentos del proyecto adquirir una estructura razonable y un buen diseo a
bajo costo?

Efectivo Hemos visto que el diseo y la materia formato. Un buen diseo hace que un documento ms legible. Los
documentos del proyecto deben cumplir con un cierto grado de estndares de formato.

Sin embargo, es ineficiente para permitir que los miembros del equipo se encargan de cosas como el diseo y el
formato de forma individual. Todo el mundo vendra con su indicacin
140 Infraestructura y Organizacin Tcnica

soluciones viduales, por lo que no seran una apariencia consistente a travs de los documentos del
proyecto. Ms importante an, sera un desperdicio de recursos. En un proyecto gil, asumiendo una
actitud gil, no todo el mundo tiene el tiempo para disear diseos de documentos. E incluso si varias
personas se tomaron el tiempo, acabaran haciendo cosas similares de forma independiente el uno del
otro. Por ltimo, es probable que no todos en el equipo tiene el conocimiento para llegar a un diseo til.

La reutilizacin de diseos de documentos bien diseados suena como una buena idea. Sin embargo, no es slo el
diseo del documento que podemos reutilizar.

La mayora de los proyectos tienen alguna experiencia con los contenidos tpicos de documentos especficos. Ellos
saben qu tipo de materiales debe entrar en un requisito especfico fi cacin, o en un documento de diseo, y as
sucesivamente. Vale la pena la reutilizacin de esta experiencia, de modo que los miembros del equipo no necesita
Re-inventar los elementos tpicos de un documento tienen la intencin de escribir.

Solucin plantillas de documentos, una vez que han sido diseados adecuadamente, imponen su estructura
y el diseo de todos los documentos que se producen de usarlos.

Casi todos los procesadores de texto permiten a los modelos que se utilizarn como base para nuevos documentos:

Una plantilla define el diseo de todos los documentos de un tipo especfico. todo el conjunto de
plantillas de documento define un diseo para ser heredado por los documentos del proyecto, como se
muestra en la Figura 41. Adems, las plantillas se pueden garantizar, al menos hasta cierto grado de
general, un aspecto coherente en toda la documentacin del proyecto.

Una plantilla especi fi ca la estructura de todos los documentos de un tipo espec fi co, o al menos parte de
ella. Por ejemplo, una plantilla puede incluir las secciones y subsecciones que todos los documentos fi
caciones requieren, mientras que deja ms estructuracin a los autores de las especificaciones
individuales. Incluso puede incluir algn texto de la muestra como una especie de prototipo.

Idealmente, una persona o un pequeo grupo de personas, puede proporcionar todas las plantillas necesarias, y el
resto del equipo no necesita preocuparse con cualquier diseo y formato. Las plantillas pueden incluso estar
disponible para toda la organizacin, por lo que un proyecto slo puede volver a utilizar el trabajo de proyectos
anteriores.
plantillas de documentos 141

Figura 41. Las plantillas de documentos

Discusin Para asegurarse de que las plantillas conducen a los documentos que son altamente legible y
estticamente agradable, las plantillas deben seguir los patrones tipogrficos desde el captulo 3, de
lo contrario los errores tipogrficos y diseos torpes se copian en muchos documentos.

A continuacin, las plantillas deben ser fciles de usar. A menudo, las plantillas relativamente simples hacen
perfectamente bien. Hasta cierto grado, su simplicidad se puede medir por cmo una plantilla emplea el SEPARACIN
DE CONTENIDO Y DISPOSICIN: la plantilla normalmente formatos de prrafo de fi ne para los autores de los
documentos del proyecto para su uso. Un pequeo conjunto de formatos de prrafo, digamos diez o menos, casi
siempre es su fi ciente. Un amplio conjunto de formatos, sin embargo, hace que las plantillas complejas y di fi culto
a utilizar.

Cmo funciona exactamente plantillas puede proporcionar una estructura provisional para un documento? Una plantilla
puede introducir marcadores de posicin para los elementos estructurales descritos en el Captulo 2, en particular para DIRECTRICES
PARA LOS LECTORES, para GLOSARIO y por una
HISTORIA DEL DOCUMENTO.

Las plantillas pueden hacer ms que esto, sin embargo. Si usted decide tener una plantilla para cada
documento de la CARTERA DE DOCUMENTACIN, puede configurar secciones para todos los temas que
normalmente se tratan en estos documentos.
142 Infraestructura y Organizacin Tcnica

Por ltimo, para una coleccin de plantillas de documentos para ser generalmente disponibles, que se conservan mejor en
un lugar bien definido fi-de dentro del proyecto de DOCUMENTO DE ARCHIVO.
Para asegurarse de que los usuarios hallar las plantillas fcilmente, estos archivos deben someterse REORGANIZACIN
A PETICIN solamente.

pocas herramientas

Problema Cmo pueden los proyectos minimizar el esfuerzo dedicado a la introduccin y el uso de herramientas de
documentacin?

Efectivo Queremos producir documentacin de alta calidad. herramientas adecuadas son necesarias para la produccin,
mantenimiento, impresin, almacenamiento y recuperacin de documentos. Pero qu herramientas debemos
elegir?

Con este fin, hemos de recordar que la introduccin de herramientas trae consigo un esfuerzo de aprendizaje. Los
equipos deben familiarizarse con las herramientas antes de que puedan usarlos e fi cientemente. El esfuerzo que se
dedica a esto puede llegar a ser bastante grande cuando un gran nmero de herramientas est implicado y, lo ms
importante, cuando las herramientas son complejas en uso. herramientas complejas se pueden convertir fcilmente a la
carga en lugar de apoyar a los usuarios.

Para hacer la ltima declaracin suene ms positivo: podemos reducir el esfuerzo si se logra con menos y
ms simples herramientas.

El esfuerzo asociado con herramientas depende tambin de las herramientas que los miembros del equipo han utilizado

anteriormente. Las cosas son mucho ms fciles si un equipo puede contar con herramientas que muchos de los

miembros del equipo han estado utilizando durante aos. Por otra parte, hay una ventaja de costos en el uso de

herramientas que estn disponibles dentro de la organizacin, ya que no se necesitan licencias para herramientas

adicionales. Esto nos viene bien, ya que no queremos gastar una cantidad excesiva de dinero en la infraestructura de la

documentacin.

El argumento de los costes, sin embargo, no debe llevarnos a decidir sobre las herramientas que en ltima instancia no
hacen cumplir fi l su propsito. La mejor ventaja de costos no vale mucho cuando la herramienta no puede proporcionar el
servicio que se necesita.
pocas herramientas 143

Solucin Casi todos los proyectos pueden manejar con un pequeo conjunto de herramientas de documentacin.

La siguiente tabla muestra una lista de herramientas que pueda necesitar un proyecto.

Herramienta Propsito

Procesador de textos Producir todos los textos en documentos de papel, incluyendo


diagramas y tablas

editor HTML Producir pginas Web, a menos que puedan ser generados

Cmara digital Capturar la salida de talleres y debates pizarra

Hoja de clculo El trabajo en hojas de planificacin

lector PDF Leer e imprimir documentos listos para la impresora

navegador web Leer documentos en lnea

sitio web Hacer que la documentacin de los proyectos disponibles

gestin con fi almacenar los documentos y las versiones del documento

guracin

Cuando tienes una seleccin de productos rentes cultades para cada categora, los siguientes criterios
pueden ayudar a tomar una decisin:

Calidad: herramientas deben ser fiables y fciles de usar.

Disponibilidad: herramientas que estn disponibles en la organizacin cuestan menos que las herramientas que
necesitan para comprar.

Costo: si la calidad y la disponibilidad no son el factor decisivo, pagar tan poco como sea posible.

La pauta general a seguir es que el apoyo de herramienta para la documentacin debe ser lo ms simple
posible.

A veces los proyectos se inclinan a utilizar herramientas ms complejas, tales como herramientas CASE que tambin
apoyan la documentacin. Antes de un proyecto toma una decisin en una herramienta de este tipo, sin embargo, tiene que
ser capaz de explicar por qu es necesaria la herramienta, y cmo ayuda el equipo ms que herramientas ms simples
podan.
144 Infraestructura y Organizacin Tcnica

Discusin El manifiesto gil da preferencia a los seres humanos y la interaccin de los procesos y las herramientas
(como se cita en el libro de Alistair Cockburn (Cockburn 2001)). Esto no quiere decir que no hay ningn valor
en las herramientas, pero nos recuerda que las herramientas deben servir a las personas y no al revs. Scott
Ambler recomienda el uso de la herramientas ms simples posibles, pero comenta que esto no siempre es lo
mismo que herramientas sencillas. El grado apropiado de simplicidad depende del proyecto de REQUISITOS
documentacin individual.

Un ejemplo de una herramienta sencilla es la cmara digital, se menciona en la tabla de la pgina 143.
Puede sorprender que la veas en la lista de herramientas de documentacin, pero tiene mucho
sentido. Una cmara digital es fcil de usar, y puede convertir los resultados de los debates de la
pizarra en ESQUEMAS juiciosa. Esta tcnica se ha sugerido en la literatura sobre el desarrollo gil
(Cockburn 2001, Ambler 2002).

En lo que se refiere a los procesadores de texto, asegrese de que la herramienta que se utiliza es compatible
con la generacin de PDF, preferiblemente de una manera directa. Esta es la forma ms fcil de lograr una SEPARACIN
DE procesamiento y la impresin. Tambin dar preferencia a las herramientas que tienen un enfoque tcnicamente
slida a la SEPARACIN DE Contenido o de presentacin por ejemplo, ofreciendo una forma sencilla para de fi ne
formatos de prrafo.

Los cambios anotado


Problema Cmo pueden los autores evitar la confusin sobre los cambios que han hecho?

Efectivo Mientras que un documento est todava en desarrollo, los cambios se realizan con frecuencia. Esto no representa
un problema, siempre y cuando slo una persona est involucrada en la redaccin del documento.

Documentacin, sin embargo, puede ser un esfuerzo de colaboracin. Varias personas pueden contribuir a un
documento como co-autores. Co-autor de un documento es mucho ms eficaz si todos los autores son
conscientes de los cambios recientes en los que otros han hecho.

Registro de cambios recientes viene a la mente como una solucin, y la mayora de los procesadores de texto ofrecen esta

caracterstica. Pero a medida que se hacen ms cambios, el tamao de los registros de cambios crece y crece, y despus de un

tiempo los registros se convierten en demasiado tiempo para ser til.


Notificacin sobre la actualizacin 145

Solucin Mientras que un documento se encuentra en desarrollo, los autores pueden utilizar las anotaciones automticas
para identificar aquellas partes del documento que han cambiado recientemente.

Los procesadores de texto ofrecen las siguientes tcnicas para controlar los cambios realizados en un documento:

Cambio de barras en el margen exterior indican los prrafos que han cambiado recientemente.

Nuevo texto puede aparecer en diferentes colores, incluso indicando la persona que agreg el texto.

El texto que ha sido eliminado todava puede ser visible, pero tachado.

Las anotaciones se pueden anexar al texto que dicen que los ltimos modificados y cundo.

Una vez que un documento ha llegado a un estado estable, se distribuye entre el equipo, o incluso se
entrega al cliente, tales anotaciones deben ser eliminados. No slo iban a estorbar el documento y
destruir el diseo general, que no tendran sentido para la mayora de los lectores.

Discusin Este patrn es de gran utilidad cuando un documento est escrito por los co-autores como un esfuerzo
conjunto. Sin embargo, otro patrn recomienda que cada documento tiene
UNO Autor responsable. Es esto una contradiccin? No, no lo es: la co-autora de un documento es
perfectamente natural. El trabajo del autor responsable es asegurarse de que el documento est escrito
segn lo previsto, y si hay co-autores, que las contribuciones se integran sin problemas. Cambio bares
y anotaciones estn ah para ayudar al autor responsable.

Notificacin sobre la actualizacin

Problema Cmo se pueden prevenir los lectores del uso de versiones no actualizadas?

Efectivo La informacin puede expirar, en particular, en un proyecto que todava no se ha completado. se aaden
nuevos documentos, los documentos existentes se actualizan. Normalmente queremos que nuestros colegas
que lean las versiones ms recientes de los documentos, ya que las versiones ms recientes representan lo
mejor de nuestro conocimiento. Pero, cmo puede la gente sabe que hay un documento nuevo, o una nueva
versin de un documento existente?
146 Infraestructura y Organizacin Tcnica

No se puede esperar que la gente compruebe el archivo regularmente para las nuevas versiones. Y hay poco beneficio
en pedir a la gente a usar sus documentos en lnea para que puedan obtener nuevas versiones de forma automtica.
Dado que la impresin es el medio de eleccin para muchos documentos, la gente va a imprimir esos documentos de
todos modos, y cambios seran entonces pasar desapercibido.

As que hay que informar a la gente cuando un documento ha cambiado. Sin embargo, el grado de detalle debe
ser la informacin? Informacin sobre actualizaciones debe ser lo suficientemente detallada para que las personas
deciden si una nueva versin es relevante para ellos.

Sin embargo, no es una buena idea enviar un mensaje de correo electrnico que incluye la nueva versin de s mismo. Esto
slo se asegurara de que el documento se almacena de forma redundante muchas veces en los buzones de correo de los
destinatarios.

Solucin Cada vez que hay un cambio significativo en un documento de proyecto, todos los lectores
potenciales deben ser noti fi cado de la nueva versin. La noti fi cacin debe explicar ms o
menos lo que se ha cambiado, pero no debe incluir el material actualizado en s.

A menudo, el correo electrnico es el mtodo de eleccin para notificar a los lectores. El catin notificada debe
incluir la siguiente informacin:

Qu documentos se han aadido o actualizado, y los nmeros de versin pertinentes.

Por qu se hizo necesaria la nueva versin, y que el material es nuevo.

Un puntero a donde las nuevas versiones se pueden encontrar.

Discusin noti fi caciones se hacen necesarias como consecuencia de hacer CONTINUACIN DE DOCUMENTACIN, causado
por la necesidad de desarrollar software y la documentacin al mismo tiempo. El nmero de versin y la lista
de los cambios propuestos en el catin fi NotI deben estar sincronizados con el HISTORIA DEL DOCUMENTO que
aparece en el propio documento.

Antes de enviar la noti fi cacin de una nueva versin de los lectores, el autor debe asegurarse de que la
nueva versin se ha registrado en el DOCUMENTO DE ARCHIVO. La indicacin del lugar donde la nueva versin
se puede encontrar a continuacin, es un puntero a la ubicacin en el archivo donde se almacena la versin.
Cuando se aaden nuevos documentos, informando a los lectores potenciales puede no ser suficiente - la documento
horizontal puede ser necesario actualizar tambin.
Reorganizacin a peticin 147

Reorganizacin a peticin
Problema Cmo se puede mantener la infraestructura de la documentacin?

Efectivo Una infraestructura estable es un factor clave para la documentacin til. Los usuarios esperan que los documentos
que se almacenan en lugares especficos, esperan herramientas para trabajar de una manera particular y as
sucesivamente. reorganizacin frecuente confunde a todo el mundo. Sin embargo, en algn momento de la
reorganizacin de la infraestructura puede llegar a ser inevitable. Cuando un proyecto se inicia la infraestructura de
documentacin no puede ser completa. A medida que el proyecto evoluciona, los requisitos adicionales para desarrollar
la infraestructura. Tal vez la jerarqua en la que los documentos se organizan necesidades a extenderse, tal vez
plantillas de documentos adicionales se hacen necesarios y as sucesivamente.

Sin embargo, la reorganizacin representa una buena cantidad de esfuerzo. La adaptacin de las vas de acceso, comprobando

si las herramientas an funcionan y as sucesivamente son tareas tpicas que siguen reorganizacin. Esto hace que la

reorganizacin bastante caro.

Adems, una infraestructura casi nunca es perfecto; que casi siempre se puede mejorar. Este hecho
por s solo no justifica la reorganizacin. Hacer una infraestructura til incluso mejor casi no vale la
pena.

La experiencia demuestra que, cuando la gestin de la documentacin se ejecuta sin problemas, los usuarios slo
utilizan la infraestructura de documentacin. Cuando la infraestructura de la documentacin es problemtico hasta el
punto de que la reorganizacin se hace inevitable, los usuarios piden activamente cambios.

Solucin reorganizacin frecuente empeora las cosas, no mejor. Reorganizacin de la infraestructura


de la documentacin debe tener lugar slo cuando es solicitado activamente por los
miembros del equipo del proyecto.

Reorganizacin debe cumplir con los siguientes requisitos:

Los bene fi cios esperados deben justificar el esfuerzo que es causada por las consecuencias de
documentos, herramientas o mtodos existentes.

Los esfuerzos del proyecto suben y bajan en ciclos naturales, a veces de un ao, a veces de medio
ao. Este perodo es un perodo de tiempo umbral durante el cual debe ser probable que una mayor
reorganizacin no ser necesario. En otras palabras, si usted est a cargo de la gestin de la
documentacin, que debe tomar las quejas de los usuarios acerca de la infraestructura de la
documentacin SERIAS
148 Infraestructura y Organizacin Tcnica

ormente, pero no debe reaccionar de forma exagerada a los pequeos problemas que, si bien pueden existir, apenas son
cruciales.

Discusin La reorganizacin de la infraestructura de la documentacin tiene una serie de consecuencias. Puede afectar a la plantillas
de documentos de dos maneras diferentes. En primer lugar, su ubicacin en el DOCUMENTO DE ARCHIVO puede cambiar,
y en segundo lugar, las propias plantillas pueden ser reorganizadas. Este ltimo, si se hace mientras que un
proyecto est en curso, puede poner el diseo coherente de los documentos existentes y futuros en riesgo.

Reorganizacin tambin influye en el uso de herramientas. En primer lugar, esto es cierto para un sistema de
gestin con fi guracin utilizada en el DOCUMENTO DE ARCHIVO, los cuales al menos las necesidades de sus vas de
acceso ajustados. Pero quizs tambin la jerarqua de archivo se ve afectada: en este caso la reorganizacin
debe preservar o recrear, la claridad y el equilibrio estructural del archivo.

En segundo lugar, la reorganizacin afecta a los mecanismos que generan automticamente los documentos siguientes a
la FUENTE NICA Y OBJETIVOS DE MLTIPLES principio, as como los mecanismos para IMPORTACIONES POR REFERENCIA. Una vez
ms, las vas de acceso deben ser actualizados.

Programacin y documentacin - una analoga


Hay una analoga interesante entre varios de los patrones en este captulo y varios principios de programacin.

La creacin de una DOCUMENTO PAISAJE e implementarla mediante un DOCUMENTO DE ARCHIVO se asemeja a los principios de
las estructuras de datos y su representacin fsica. El hecho de que se trata de dos modelos tiene sus races en la idea de
que especi fi cacin y aplicacin deben estar separados.

los SEPARACIN DE Contenido y disposicin contribuye a la disociacin, que se suma a la flexibilidad de un documento. Esto es similar
a la flexibilidad obtenida por un sistema de software a travs de componentes de desacoplamiento despus de la "separacin
de las preocupaciones de principio.

La discusin de formatos en el SEPARACIN DE procesamiento y la impresin es paralela a la discusin de formatos de


intercambio de datos conocidos de ingeniera de software.

El uso de DOCUMENTO PLANTILLAS promueve la reutilizacin a travs de un mecanismo similar a la herencia. plantillas de documentos
proporcionan estructuras que se reutilizan muchas veces.
Informes de experiencia 149

Teniendo un SOLTERO FUENTE Y OBJETIVOS MLTIPLES as como la IMPORTACIONES POR REFERENCIA Evitar tcnica (o al menos
administrar) redundancia mediante la adicin de un nivel de indireccin. Una cierta prdida de e fi ciencia es aceptada con el fin
de facilitar el mantenimiento. Se puede hallar la misma disyuntiva en desarrollo de software.

El principio de NOTIFICACIN EN ACTUALIZACIN se asemeja en gran medida arquitecturas de software basadas en eventos.

REORGANIZACIN EN SOLICITUD discute el equilibrio entre la ventaja de una mejor organizacin y los costes de
reorganizacin - una discusin que se pueden encontrar en muchos proyectos de software.

Estos principios son tan importantes en la documentacin como en la ingeniera de software. A menudo la gente no
se dar cuenta de su aplicacin, y slo se perder ellos cuando no se aplican. Estos principios ayudarle a seguir un
estilo de programacin directa en una mano y una organizacin gil de su documentacin por el otro.

Informes de experiencia
Veamos ahora en la infraestructura de la documentacin de algunos de nuestros proyectos de la muestra.
Veremos las diferentes tcnicas que los proyectos utilizan para organizar su documentacin, y tambin
veremos los problemas que se enfrentan.

Almacenamiento y Si uno mira hacia atrs en la Figura 35 en la pgina 118, se puede ver lo que es un proyecto de

recuperacin de infraestructura mal organizada se parece. Entonces, cmo un bien organizado documento horizontal parece? La
figura 42 muestra cmo Proyecto Contentis organiz su documentacin.
documentos

Contentis era bastante pequeo proyecto, por lo que el equipo opt por una solucin muy simple para la organizacin
de sus documentos. Los documentos se almacenan en el sistema de archivo, y control de versiones slo consistieron
en la adicin de los nmeros de versin de los nombres de los documentos. A pesar de, o quizs a causa de su
simplicidad, esta solucin funcion muy bien.

En un proyecto ms amplio, sin embargo, una solucin ms elaborada probablemente tiene sentido.
Proyecto persistor tambin opt por utilizar el sistema fi l como base para su DOCUMENTO PAISAJE, pero
reconoci que era necesario tener un subyacente
DOCUMENTO DE ARCHIVO. Proyecto persistor era un proyecto de desarrollo, y un sistema de gestin
con fi guracin ya estaba en uso de versiones de mdulos de software. Era lgico utilizar este
sistema para la documentacin del proyecto
150 Infraestructura y Organizacin Tcnica

Las versiones PDF para

distribucin

versiones simples

basados

Figura 42. Proyecto Contentis: un sistema fi l documento paisaje claramente distinguidos directorios

as como. La Figura 43 muestra la fi le organizacin del sistema, lo que refleja la estructura dentro del sistema
de gestin de configuracin con fi, en el que las versiones antiguas no son visibles.

Navegador de proyectos se le ocurri otra solucin. Este proyecto utiliza una herramienta CASE todos
modos, y almacena varios documentos de texto dentro de ella. Adems, el proyecto tambin se sinti la
necesidad de documentacin HTML, para que puedan navegar a travs de las descripciones de los diseos
de componentes y la interfaz de especificaciones. Estos documentos HTML se colocaron en un proyecto WIKI, como
se muestra en la Figura 44.
Informes de experiencia 151

formatos adecuados
para el
procesamiento y
impresin

estructura clara

plantillas de proyecto
disponibles

integrado en la gestin de configuracin con fi

Figura 43. Proyecto persistor: Documento paisaje en la parte superior de la documentacin de gestin de con fi guracin
152 Infraestructura y Organizacin Tcnica

Figura 44. Navegador de proyectos: un documento horizontal basada en la Web

Por muy diferentes que estas soluciones son, todos ellos tienen en comn que estn bien organizados,
clara y fcil de memorizar. Se obtiene una idea de la documento horizontal y usted sabe dnde buscar para
cada documento. Todos estos ejemplos tambin hacen uso de MEDIA de fcil lectura. Tanto el Proyecto y el
Proyecto persistor Contentis eligieron para producir documentos destinados a
Informes de experiencia 153

Proyecto persistor: una estructura de sistema le sencillo fi

La infraestructura para todos los archivos del proyecto se cre en cuanto el proyecto haba comenzado. Esto incluye tanto los
documentos del proyecto y cdigo fuente. Estaba claro que el equipo se utilice un sistema de gestin con fi guracin para el
cdigo, por lo que fue una decisin fcil de utilizar el mismo sistema para archivar los documentos del proyecto as.

Los documentos que describen el marco de la capa de acceso de datos se almacenan en bien organizada fi l de los directorios del
sistema que eran accesibles por todo el equipo del proyecto para la lectura y la escritura (Figura 43). El sistema de gestin de con fi
guracin subyacente se asegur de que un documento tuvo que ser retirado antes de que alguien pudiera cambiarlo, y que las
versiones anteriores se pudo recuperar si es necesario.

imprimir, y aplicado esto a travs de la generacin de PDF. Como se puede ver en las figuras 42 y 43,
ambos proyectos han proporcionado versiones PDF de los documentos que iban a ser distribuidos.

Navegador de proyectos enfrent fuertes peticiones de navegacin a travs de la documentacin del


proyecto, y por lo tanto suministra versiones en lnea de algunos documentos. Proyecto Flexicar lleg a la
misma conclusin. Este proyecto decidi proporcionar informacin especfica en lnea a peticin del
cliente. En ambos casos, el alto grado de referencialidad haba llevado a documentos en lnea como MEDIA
de fcil lectura.

Flexicar proyecto: la generacin de documentos de ejecucin


Adems de los documentos de diseo producidos, el cliente estaba interesado en la documentacin de la aplicacin
real.

JavaDoc era la herramienta perfecta para generar esta documentacin sin ningn esfuerzo adicional. El equipo haba suministrado los
comentarios de cdigo fuente siempre que sea necesario, y haba seguido las directrices para los comentarios de Java desde el principio.
Por lo tanto, un comentario de HTML para todas las clases se podra generar en ningn esfuerzo adicional.

La produccin de Esta discusin nos lleva a la cuestin de cmo se produjeron estos documentos en lnea. Los documentos en

documentos lnea, tanto en Navegador de proyectos y en el proyecto Flexicar, incluidas la informacin que se origin en
otro lugar. Esto no fue un problema, sin embargo, ya que en ambos casos las versiones en lnea podra ser
generados automticamente. Navegador de proyectos gener sus documentos de forma automtica a partir de
una herramienta CASE. Proyecto Flexicar haba seguido el principio de CODIGO-COMENTARIO
154 Infraestructura y Organizacin Tcnica

PROXIMIDAD y haba suministrado ricos comentarios de cdigo fuente en los puntos cruciales en el
software, lo que permite JavaDoc a emplear.

Esto demuestra los bene fi cios que las herramientas pueden aportar muy bien: se puede ahorrar trabajo extra.

trabajos de mantenimiento dobles y dobles son cosas que queremos evitar con claridad - que no queremos para

documentar lo mismo dos veces. Proyecto Vista da otro ejemplo de cmo una herramienta puede ayudar en este

caso. Una vez ms, la informacin que se haba hecho disponible en diferentes formatos, y que tiene una

FUENTE NICA Y OBJETIVOS DE MLTIPLES fue la clave para controlar la redundancia.

Proyecto Vista: generar una tabla a partir de un diagrama

El diagrama del paisaje de aplicacin (Figura 7, pgina 54) revel la mayor parte de las dependencias entre los
sistemas utilizados el cliente. El diagrama se mantuvo utilizando Microsoft Visio y se actualiza cada vez que el equipo
gan ms penetracin en entorno de las aplicaciones del cliente.

El diagrama era perfecto para repartir y para conseguir las discusiones iniciadas. El diagrama no era apropiado, sin
embargo, para una descripcin ms detallada de las dependencias El equipo haba identificado fi. Lo que se necesitaba era
una lista de todas las dependencias, a la que se podra aadir ms informacin y que permiti que las dependencias a
clasificarse.

El equipo decidi mantener una lista de todas las dependencias del sistema en una hoja de clculo de Microsoft Excel. Esta hoja
de clculo era demasiado grande para ser mantenido de forma manual. Una persona escribi un pequeo script que extrae la
informacin sobre las flechas que conectan las cajas en el diagrama de Visio y se transforma esta informacin en un formato que
pudiera ser importado en la hoja de clculo.

Este fue un mecanismo relativamente fcil que se implement en unas pocas horas. Se trabaj e fi cientemente suficiente para
permitir que la hoja de clculo para actualizarse sobre una base casi diaria.

Sin embargo, el Proyecto Navigator tambin tiene una advertencia para nosotros. Se tom este proyecto un tiempo
antes de que la infraestructura de la documentacin estaba en marcha, lo que caus algunos problemas. Una vez
que se estaba ejecutando, se reorganiz varias veces. La gente tena que ajustar configuraciones fi herramienta
Evaluacin condicional ms de una vez. En lugar de realizar una REORGANIZACIN A PETICIN, reorganizaciones
innecesarios utilizan recursos que podran haberse gastado mejor en otro lugar.
Informes de experiencia 155

Navegador de proyectos: la integracin de diseo y documentacin

El equipo realmente tena sentimientos encontrados acerca de la documentacin en este proyecto. La parte buena es que
el proyecto sigui la estrategia de documentar todo lo ms una vez. El cliente haba sugerido el uso de mecanismos de
generacin de evitar el mantenimiento de los documentos redundantes.

Rational Rose fue utilizado como una herramienta de modelado. Para cada componente, el modelo de Rose incluye una
descripcin, un diagrama de clases y la interfaz de especificacin. Un marco de cdigo para cada componente podra ser
generada de forma automtica, que inclua comentarios de cdigo ce amarga por los mtodos de interfaz.

Adems, el cliente quera un documento de diseo pequeo para cada componente. Este documento tambin
consisti en la descripcin, el diagrama de clases y la interfaz espec fi cacin, y se gener a partir del modelo de
Rose.

Varios desarrolladores consideraron que las versiones en lnea de los documentos de diseo eran muy til, ya que utilizan
estos componentes en su programacin diaria. pginas HTML se generan automticamente y se integran en la
documentacin general de la web del proyecto haba establecido (Figura 44).

El inconveniente era que tom bastante tiempo antes de establecerse la infraestructura. En primer lugar, se tom el tiempo para un
directorio fi l sistema para definirse a la que todo el equipo tuvo acceso. Esto fue principalmente porque el equipo trabaj en diferentes
sitios. Hasta que el problema se resolvi, los miembros del equipo recurrieron a hacer circular documentos a travs de correo
electrnico cada vez que se hizo una actualizacin disponible. La gente pronto tenan un montn de diferentes versiones de los
documentos del proyecto en sus buzones, lo que llev a varios conflictos en los que alguien utiliza una versin obsoleta.

En segundo lugar, se tom un tiempo antes de que todos los mecanismos de generacin estaban en funcionamiento. Hasta que esto se hizo,
los componentes de Rose modelo y diseo de documentos se mantuvieron de forma redundante, a pesar de un intento de evitar esto.

Por ltimo, la infraestructura, y en particular los mecanismos de generacin, se someti a una reorganizacin frecuente. El
equipo tuvo que usar diferentes mecanismos varias veces, lo que provoc una sobrecarga significativa.
156 Infraestructura y Organizacin Tcnica

Del mismo modo, el Proyecto Paracelso se meti en problemas porque tom demasiado tiempo para hacer
la infraestructura de la documentacin disponible. En este caso, el plantillas de documentos faltaban. Proyecto
persistor muestra cmo este problema especfico debe ser resuelto: las plantillas de proyecto se almacenan
en el documento horizontal
junto con todos los otros materiales (Figura 43).

Proyecto Paracelso: las plantillas que faltan

Cuando el equipo comenz a escribir la memoria descriptiva y los documentos de diseo, no hay plantillas para estos documentos estaban
disponibles debido a que la organizacin no proporcion ninguna. El equipo tuvo la posibilidad de elegir el diseo de una plantilla por su
propia cuenta o hacerlo sin una. Unas semanas despus el proyecto, una persona se tom el tiempo para configurar una plantilla de
documento simple. En ese momento, sin embargo, todo el mundo ya haba estado trabajando en sus documentos, que tenan una
estructura bastante inconsistente y el diseo como resultado. La mayor parte de los documentos carecan de algunos de los elementos que
son tiles para los lectores: directrices, un historial de documentos y as sucesivamente.

Los documentos fueron adaptadas manualmente a la nueva plantilla. Fue un proyecto pequeo con slo unos pocos
documentos, por lo que el dao podra ser reparado rpidamente. Sin embargo, ms tiempo de lo necesario se gast en dar
a esos documentos una estructura adecuada, por no hablar de formato y diseo. Haba estado disponible la plantilla desde el
principio, el doble de trabajo se podra haber evitado.

La conclusin que podemos sacar de estos ejemplos es que una infraestructura claro y efectivo es el mejor
soporte tcnico para la documentacin que se puede tener. Cuanto antes la infraestructura disponible, el
mejor. plantillas de documentos son una parte esencial de esta infraestructura, que son herramientas simples,
siempre que evitan la duplicacin del trabajo. Casi todos los proyectos pueden manejar con HERRAMIENTAS
pocos, siempre que las herramientas funcionan de forma fiable y e fi ciente. De todos los proyectos
mencionados aqu, ninguno se bas en herramientas complejas que eran dif fi cil de usar. La simplicidad y la
sencillez fueron las estrategias que han funcionado bien, mientras que los problemas fueron causados por la
complejidad, la reorganizacin frecuente y las infraestructuras estn aplicando demasiado tarde en el
proyecto.

Me gustara concluir este informe experiencia con un ejemplo de lo fcil y eficaz puede ser soporte
de herramientas. Entre otros, Alistair Cockburn y Scott Ambler recomiendan el uso de una cmara
digital para documentar discusiones de diseo (Cockburn 2001, Ambler 2002): aqu es un ejemplo
de proyecto
Informes de experiencia 157

Puertas abiertas. Es el resultado de una discusin pizarra que describe los procesos de implementacin
de un portal de Internet. Es un diagrama til, y tard slo unos diez minutos para comprometerse a
papel.

Figura 45. OpenDoors del proyecto: una instantnea cmara digital


5 Gestin y Calidad
Garanta

El valor de la documentacin slo debe realizarse si la documentacin est bien hecho. Si est mal
hecho, ser peor que no tener la documentacin en absoluto.

Gerald M. Weinberg (Weinberg 1998)

Martin y Daniel, los programadores, y Laura, el director del proyecto, se sentaron alrededor de la cafetera,
beber caf y discutir los ltimos resultados de ftbol. Laura dijo: "Oh, s, una cosa me haba olvidado en la
reunin del proyecto - Qu vamos a hacer con la documentacin? 'Hmm ... que quieres decir, se supone
que debemos hacer documentacin?' 'Bueno, seguro que somos.' 'Ok, pero no podemos hacer que cuando
hemos completado la prxima liberacin de cdigo? Tenemos absolutamente ningn tiempo para eso ahora.'

La conclusin a extraer de esta historia no es que no se debe planear la documentacin de su


proyecto en la cafetera. Si decide sentarse juntos en un ambiente agradable y planificar su
proyecto con una taza de caf en la mano, no hay nada de malo en eso.

Tampoco es la conclusin de que se debe sacrificar la prueba antes de la liberacin de cdigo, pasar el
tiempo en la documentacin en su lugar, y entregar software que no ha sido probado.

Sin embargo, algo est mal aqu. Documentacin, cuando se pone ese tipo de atencin, probablemente ni
siquiera vagamente cumplir con sus propsitos. Los documentos importantes es probable que sean
desaparecidos, debido a que el director del proyecto y el equipo se olvid de planear la documentacin en el
lugar primero. Estn discutiendo la documentacin entre otras reuniones y en realidad no lo toman en serio. Esta
no es una estrategia que garantice que los esfuerzos de documentacin estn bien orientados. Los documentos
160 Gestin y Aseguramiento de la Calidad

Una actividad
consiste en representa
distinta

ESCRITURA Y DOCUMENTACIN
REFLEXIN est coordinado por CONTINUA

requiere

es responsable
para
responsable
REVISIN ANTES DE

ENTREGA es responsable
AUTOR
para

conduce
se
a
complementa puede invitar a

por
al

documento
CRTICA DE Marketplace
es la
CONSUMIDOR Informacin se extiende
condicin previa
hacia la toma de un a
para

puede tomar
puede invitar a
en
es la condicin es un paso
previa para

GESTIN DEL
REVISIN CULTURA Una vista distante
CONOCIMIENTO

Figura 46. Patrones para la gestin y control de calidad


Una actividad distinta 161

que hacen que se escriba bien podra terminar como un montn de documentos 'de una sola escritura-lectura que nunca', por lo que

no ofrecen ningn beneficio para los lectores.

La documentacin no se produce automticamente. Tienes que procurar que la documentacin se lleva a


cabo, y que se lleva a cabo de una manera que fi cios a las necesidades de su proyecto. La planificacin no
es necesario, y no debe, ser confundido con una metodologa de peso pesado o incluso con una burocracia
documentacin. La planificacin significa simplemente que tomar las decisiones necesarias. Cuando se
decide sobre la documentacin que necesita para equilibrar las fuerzas siguientes. Por un lado, la
documentacin de alta calidad requiere tiempo y esfuerzo, pero por el otro, el tiempo y el esfuerzo son
recursos valiosos que deben ser gastados con cuidado. La clave es asegurarse de que el esfuerzo gastado
en la documentacin que se gasta bien.

Un paso es identificar los materiales que realmente debera ir en documentos escritos. Esto ha sido muy
discutido en el captulo 1. El siguiente paso es identificar las personas que deben trabajar en la
documentacin. Gestin siempre debe ocuparse de las personas, y la gestin de la documentacin no
es una excepcin. preferencias y habilidades personales de los miembros del equipo juegan un papel
aqu. Cmo se puede apoyar a los autores de la documentacin del proyecto? Sin embargo, otro paso
es involucrar a la garanta de calidad. Estos son temas los patrones en esta direccin captulo.

Es hora de afirmar una vez ms que este libro no presenta un mtodo de documentacin lista para ser
utilizada por el director del proyecto. Los siguientes patrones no dicen quin debe escribir documentos
espec fi cos y en qu momento. Ms bien, ellos guan a configurar su propia forma de documentar los
proyectos y montaje de experiencia en su organizacin. La Figura 46 proporciona una visin general.

Una actividad distinta


Problema Cmo se deben asignar recursos a las actividades de documentacin?

Efectivo La documentacin puede ser importante para las etapas posteriores del proyecto o para el prximo proyecto. Si
producimos documentacin inexacta o ignorar por completo los requisitos de documentacin, gran parte de la
experiencia realizada por los miembros del equipo se perdern. El resultado es que tendremos que volver a
inventar cosas ms tarde, debido a la falta de documentacin en el primer lugar.
162 Gestin y Aseguramiento de la Calidad

Sin embargo, la documentacin se une recursos. Estos recursos no se pueden utilizar para otras cosas como
la programacin o la prueba. Es intil discutir que la documentacin que se debe dar tanto tiempo como sea
posible. En primer lugar, la documentacin no recibe automticamente mejor cuando se pasa ms tiempo en
l. En segundo lugar, la documentacin no siempre tiene por qu ser perfecto.

El desarrollo gil sugiere que la documentacin que ser suficiente, pero no ms que eso. Es
inaceptable que un proyecto de desarrollo termina con una serie de documentos agradables pero sin
software operativo cuando el plazo de vencimiento.

Por tanto, debemos pasar una razonable cantidad de tiempo en la documentacin de los proyectos de
software. Pasar tiempo en la documentacin debe ser fi justificado por los beneficios esperados.

Pero lo que es una cantidad razonable de tiempo? No hay una respuesta general a esta pregunta, ya que los
proyectos difieren mucho - un proyecto de desarrollo es probable que tengan diferentes exigencias en la
documentacin de un proyecto de consultora, por ejemplo. Un fenmeno psicolgico conocido hace que el
asunto an ms di fi culto. Muchas personas son reacias a invertir en algo que slo paga apagado ms
adelante. Este fenmeno es an ms marcada si slo los dems no fi pro t. Si vas a gastar tiempo
escribiendo los documentos del proyecto, que no es necesariamente lo que se bene fi ciarse de esos
documentos - ms probable que sus colegas o sus clientes. Por otra parte, incluso si fi nes de los
documentos usted mismo, usted tiene que invertir tiempo, pero no obtendr ningn beneficio hasta ms
tarde.

Todo esto requiere una planificacin, y la planificacin debe tener en cuenta los bene fi cios que la
documentacin tiene para todo el proyecto, tanto ahora como en el futuro. Esto puede parecer obvio, pero
tambin muchos proyectos han terminado con documentacin insuficiente, ya que no tena intencin de
documentacin correctamente en el primer lugar.

Planificacin, sin embargo, no se limita a la asignacin de un presupuesto. Un presupuesto no vale mucho cuando un
equipo est demasiado ocupado con otras actividades del proyecto - que siempre tienen mayor prioridad.
Documentacin necesita una razonable presupuesto y una
razonable prioridad, lo que sea 'razonable' significa en un proyecto especfico.
Una actividad distinta 163

Solucin Cuando la documentacin se considera una actividad de proyecto distinto, y no slo el subproducto de
codificacin, se le puede asignar su propio presupuesto, la prioridad y el horario. La documentacin se
puede entonces compararse con otras actividades del proyecto.

La idea central es hacer que la asignacin de recursos a la documentacin


explcito, y abierto a la discusin, en forma individual para cada proyecto. Exactamente lo que es el
presupuesto difiere razonables grandemente, dependiendo del tipo de proyecto. Lo importante es
entender que la documentacin es una actividad entre otras, y que al igual que otras actividades, que
utiliza recursos.

El director del proyecto normalmente mantiene una lista de todas las actividades del proyecto con un presupuesto
asignado a cada actividad, que suman el presupuesto total del proyecto. Todas las actividades de documentacin
deben estar en esa lista, y un presupuesto (tiempo y recursos) debe ser asignado a cada uno.

Moderada por el director del proyecto, el equipo debe asignar prioridades a todas las actividades, debido
en un futuro prximo. actividades de documentacin, si se toma en serio, se le dar una alta prioridad en
algunos puntos y una prioridad inferior a los dems. El director del proyecto debe velar por que, en el
transcurso del proyecto, la documentacin recibe la prioridad que se necesita cuando se compara con
otras actividades del proyecto.

El equipo tambin debe ponerse de acuerdo sobre un calendario para la documentacin y fi jar una fecha de

entrega para la prxima versin de cada documento necesario. Los clientes suelen esperar que la documentacin

que se entregar en varios puntos a lo largo de un proyecto. Por supuesto, es necesario tener esto en cuenta

cuando se planea actividades de documentacin.

Discusin El tiempo y el presupuesto que necesita para la documentacin depende claramente de la cantidad de
documentacin que es necesario. Dado que los proyectos tienen documentacin individual REQUISITOS, el
esfuerzo que tiene que gastar puede variar enormemente. La eleccin de los documentos necesarios de la CARTERA
DE DOCUMENTACIN,

combinado con una buena dosis de escepticismo cuando se trata de grandes cantidades de papeleo,
le permitir determinar los recursos que necesita, y para mantenerlos dentro de lmites razonables.

La determinacin de la cantidad necesaria de la documentacin activa y explcitamente es una


estrategia tambin se recomienda en la literatura sobre el desarrollo gil. Alistair Cockburn no hace
ninguna suposicin acerca de qu o cunto docu-
164 Gestin y Aseguramiento de la Calidad

mentacin a necesidades del proyecto, pero se requiere un equipo de plantear y responder a esta pregunta, por
ejemplo a travs de un juego de planificacin (Cockburn 2001). Hay ms aspectos a la gestin de la
documentacin que el presupuesto y la prioridad. Otro tema es el de proporcionar un entorno que permite a los
autores tratan de documentacin como una mezcla de ESCRITURA y la reflexin. Por otra parte, una CULTURA REVISIN

necesita ser establecido que hace cumplir la REVISIN antes de la entrega regla. Por ltimo, pero no menos
importante, es esencial para nombrar Un autor RESPONSABLE para cada documento - preferiblemente alguien que
disfruta haciendo documentacin.

Un responsable Autor
Problema Cuntas personas deben ser responsables de un documento?

Efectivo Si un gran nmero de personas que son responsables de una tarea, es probable que la tarea no se hace
en absoluto - todo el mundo va a pensar que otra persona est a cargo.

Las responsabilidades son claras si slo una persona, oa lo sumo un pequeo equipo, es responsable de cualquier
tarea. Una idea es tener el trabajo a alguien en la documentacin del proyecto a tiempo completo, ya que esta
persona podra entonces concentrarse en el trabajo. Tal vez el proyecto, sin embargo, no puede prescindir de una
persona durante el tiempo suficiente para escribir la documentacin solo, o una sola persona no tiene suficiente
conocimiento para hacerlo. Por otra parte, una persona que trabaja exclusivamente en la documentacin no est
involucrado en otras actividades del proyecto. Es ms fcil de producir buena documentacin cuando usted est
involucrado activamente en un proyecto en lugar de simplemente observarlo. Esto sugiere que varias personas
pueden tener que contribuir a la documentacin.

A medida que las personas son diferentes, tienen diferentes intereses y habilidades. Algunos ingenieros de software
no les gusta escribir documentacin y prefieren las tareas ms tcnicas, mientras que otros que se le parezca. Si
estamos interesados en la documentacin de alta calidad, que debe asegurarse de que los autores son expertos y
motivados. Cul es el punto de obligar a alguien a hacer el trabajo que no est dispuesta a hacerlo?
Un responsable Autor 165

Solucin Para cada documento del proyecto, tiene que haber una persona que acepta la responsabilidad
por ello. Esta persona no tiene que escribir el documento solo, pero debe coordinar las
contribuciones de otras personas.

La persona responsable debe ser un miembro del equipo del proyecto, tener buenas habilidades de escritura y
tambin disfrutar de la escritura (Weir, 1997). Esa persona debe hacer lo siguiente:

Recoger el material y organizar sesiones de lluvia de ideas con otros miembros del equipo.

Establecer la estructura general del documento.

Commit material a papel.

Si hay co-autores (que a veces ser el caso), solicitar contribuciones de los co-autores e
integrar estas contribuciones, garantizando al mismo tiempo un estilo de escritura coherente
para el lenguaje, diccin y lneas de argumentacin.

Se encargar de la revisin de documentos e incorporar los comentarios de los revisores.

Diferentes documentos de proyectos suelen tener diferentes autores responsables, para asegurar que para
cada autor responsable de la carga de trabajo de la documentacin no sea demasiado grande en proporcin a
otras actividades del proyecto.

Discusin Este modelo es una versin especial de un principio de gestin general. Entre sus patrones de reduccin del
riesgo de gestin de proyectos, Alistair Cockburn hace hincapi en que en un proyecto que debe haber
exactamente una Propietario por entregable ( Cockburn
1998), de lo contrario podra funcionar a varias personas en la misma cosa, o tareas importantes podran ser
descuidada. Este principio se aplica a los documentos tanto como a todos los dems tipos de entregables, por
lo tanto, el requisito de que la responsabilidad de un documento ser asignado a una persona.

Esta responsabilidad incluye el establecimiento de un proceso para garantizar CONTINUACIN DE


DOCUMENTACIN, y organizar una REVISIN antes de la entrega.
166 Gestin y Aseguramiento de la Calidad

Documentacin continua
Problema Cuando se debe escribir la documentacin del proyecto?

Efectivo Est claro que al comienzo de un proyecto no somos capaces de documentar todo lo que nos gustara ver
documentado por el final. Todava no sabemos cul es la arquitectura de software se ver as, por no hablar
de los aspectos ms detallados de diseo. De las cosas que podramos describir ya, como los requisitos de
los usuarios, al menos algunos son propensos a cambiar a medida que el proyecto evoluciona. Sin embargo,
no podemos posponer la documentacin hasta que el proyecto est terminado. Se necesita documentacin
sobre la comunicacin con los clientes y entre los miembros del equipo. Tiene que estar disponible durante el
proyecto.

Estos puntos sugieren que la documentacin debe iniciarse al principio del proyecto, en un nivel
relativamente grano grueso, y se debe continuar, re fi nido y se actualiza con regularidad. Por ejemplo, un
documento de diseo puede comenzar como un simple boceto y puede ser extendida como el diseo
evoluciona.

La pregunta, sin embargo, es lo que queremos decir con actualizaciones regulares ''. Por un lado, si se espera
demasiado tiempo antes de documentos se actualizan, los lectores son susceptibles de ser irritado por
informacin obsoleta. La informacin incorrecta puede ser la fuente de malentendidos graves, y por lo tanto
puede hacer mucho dao. Peor an, excesivamente largos lapsos de tiempo entre actualizaciones de la
documentacin crean el peligro de que los cambios no se estn llevando a cabo en absoluto. En algn momento,
la actualizacin de la documentacin es fcil de olvidar. Esto claramente no es lo que queremos, ya que hara
que la documentacin intil en el largo plazo debido a la inexactitud.

Todo esto sugiere que debemos ser bastante rpido con las actualizaciones. Si esperamos a que surjan
problemas con los documentos obsoletos, hemos esperado demasiado tiempo - el dao ya est hecho.

Por otro lado, si la documentacin se actualiza inmediatamente cada vez que un proyecto de detalle cambios,
que tendrn que ser modi fi cado de manera casi continua. Esto es caro - la documentacin requerir mucha
ms atencin de la necesaria. Por otra parte, la actualizacin de la documentacin con demasiada frecuencia
se asegura de que la mayora de las veces no hay documentacin estable est disponible. Esto est en
conflicto con nuestro deseo de tener til documentacin, aunque incompleta, desde el inicio del proyecto.
Documentacin continua 167

Solucin La documentacin del proyecto, cuando se evoluciona continuamente a medida que el proyecto
avanza, ofrece la ventaja de que re fl eja el ltimo estado estable del proyecto.

Continuando con la documentacin exige documentacin que se actualiza a intervalos regulares.


Qu plazo puede suponer para stos r intervalos ERIDICAS depende del proyecto individual:

A menudo es una buena idea para actualizar la documentacin con las nuevas versiones de software, manteniendo
de este modo la escala de tiempo de versiones de software y documentacin en sincrona.

La frecuencia de las actualizaciones depende tambin del tipo de documento. documentos ms generales, tales
como descripciones de la arquitectura, son ms estables y tienen un menor nmero de cambios que, por ejemplo,
una interfaz especfica de cationes, que puede cambiar de un da en un proyecto ocupado.

Las actualizaciones pueden ser ms o menos urgente. Un documento importante, que se utiliza sobre una base
del da a da, debe actualizarse rpidamente cuando su objeto ha cambiado. Un documento diferente puede ser
utilizado con menor frecuencia: la actualizacin de este documento no es tan urgente y tal vez puede esperar.

La documentacin existente, quiz en su estado intermedio, debe ponerse a disposicin de todos los
miembros del equipo, para que puedan utilizarlo como avanza el proyecto.

Discusin El manifiesto gil recomienda ciclos de lanzamiento de software de un par de semanas a un par de meses (en
una de sus recomendaciones concretas, como se cita en el libro de Alistair Cockburn (Cockburn 2001)). Se da
preferencia a una escala de tiempo ms corto para que la entrega de software no se ralentiza. Un par de
semanas tambin suena como un buen promedio marco de tiempo para la actualizacin de los documentos,
aunque ms corta, as como los intervalos ms largos puede tener sentido. Entre las actualizaciones, la
documentacin no es del todo hasta la fecha. Es este un problema, y es que hay algo que podemos hacer al
respecto? Lo primero que hay que hacer es mantener una HISTORIA DEL DOCUMENTO, para que los lectores son
conscientes de inexactitudes potenciales. De lo contrario, la gente puede superar este problema mediante el uso
de una tcnica sencilla que Charles Weir sugiere entre sus Las pautas de diseo en equipo: todos los miembros
del equipo pueden tener una copia impresa de la documentacin y hacer Correcciones (adhoc Weir 1997) hasta
la prxima versin se distribuye al equipo. Afortunadamente, muchos de los documentos que se someten a
cambios rpidos son los que la gente utiliza para buscar informacin - documentos que normalmente se
presentan
168 Gestin y Aseguramiento de la Calidad

en lnea (ver De fcil lectura-MEDIA). Estos documentos a menudo se pueden generar. Por otra parte, los
documentos en papel a menudo ponen una Centrarse en la pertinencia de largo plazo, lo que reduce claramente el
problema.

Para hacer posible la documentacin continua, la documentacin debe ser considerado UN actividad distinta - una parte
integral de un proyecto que requiere la capacidad del personal y un presupuesto, al igual que todas las otras
actividades del proyecto. Para cada documento, el equipo tiene que decidir sobre la frecuencia de actualizacin y
el Un autor RESPONSABLE debe asegurarse de que se cumple la frecuencia de actualizacin.

Debido a que la documentacin est escrita y utilizar mientras avanza el proyecto, que est abierto a la CULTURA
REVISIN es de esperar que el proyecto ha establecido. Este es un problema doble. En primer lugar, escribir
documentacin puede dar una idea del software, como ESCRITURA Y REFLEXIN puede ir de la mano. Por
ejemplo, al describir un diseo, de manera implcita que validar, tanto como lo hace cuando se lo explicas
a los dems. De esta manera, la documentacin puede contribuir a la calidad del software. En segundo
lugar, como la documentacin que se utiliza durante el proyecto, los miembros del equipo pueden dar
informacin sobre la calidad de la misma documentacin.

La escritura y la reflexin
Problema Cmo pueden documentacin y otras actividades del proyecto estimular el uno al otro?

Efectivo Las buenas ideas necesitan tiempo. La documentacin es un proceso creativo, y los procesos creativos necesitan
tiempo para permitir que las ideas que se desarrollan y maduran. Un pre-requisito para un texto bien escrito es que se
da el autor de tiempo para la reflexin durante la escritura.

Esto es an ms cierto para la documentacin en condiciones de cambios rpidos. Evolving proyectos


suelen ir de la mano con el crecimiento gradual de la documentacin, que requiere autores para reflexionar
sobre los cambios y adaptaciones que necesitan para tomar.

Los autores no slo se re fl ejan en los documentos que escriben, sino que tambin reflejan en la materia.
La documentacin es un medio importante de validacin. Usted puede obtener informacin, por ejemplo,
en un diseo de software, mientras que documenta, y observe lo que es imperfecta o incompleta. Escribir
documentacin proporciona informacin sobre lo que se est documentada.
La escritura y la reflexin 169

En algunos casos, la reflexin puede ser el propsito principal de un documento. Algunas personas
obtienen sus mejores ideas en el trabajo conceptual cuando tratan de cometer el concepto de papel. Si
alguien trabaja en un documento con el fin de pensar un concepto o una idea a travs, es crucial tomar el
tiempo necesario para las nuevas ideas y la reflexin.

El tiempo no es todo, sin embargo. Los autores tambin requieren de un ambiente que les permite
concentrarse en su trabajo. Un miembro del equipo del proyecto, el autor se ocupa esencialmente de
muchas otras personas, desarrolla software, participa en debates, reuniones y talleres, y as sucesivamente.
Eso es definir, pero cuando se trata de documentacin, un poco de paz y tranquilidad puede hacer mucho
bien. La importancia del trabajo en equipo pesar de ello, una habitacin con muchas personas alrededor no
es un entorno que permite a una persona a concentrarse en la escritura.

Solucin Para sacar el mximo partido de la documentacin, los miembros del equipo tienen que pasar tiempo
en la escritura real, as como en la reflexin sobre lo que han escrito, preferiblemente en un entorno
tranquilo.

Esto se puede dividir en los siguientes consejos concretos:

materiales y estructuracin que el material consiste en la recogida de la creatividad. Es casi


imposible escribir un documento perfecto directamente hacia afuera. La eleccin del material y la
definicin de una estructura inicial documento tienen que ser objeto de reflexin. Tiene que
esperar a los contenidos y la estructura de un documento que pasar por varios pasos de
refinamiento antes de completar el documento.

Mientras escribe, usted debe comprobar la documentacin de problemas e inconsistencias. Si se


observa que las partes de la documentacin son problemticos, esto puede sugerir que es el
sujeto de la documentacin que es en s misma problemtica. De esta manera se obtiene
informacin sobre el proyecto en s.

La mayora de la gente no puede reflejar inmediatamente despus de lo que acabo de escribir.


- que necesitan para ganar un poco de distancia. Por lo tanto, usted debe dejar ningn proceso de escritura se
extienden sobre un perodo suficientemente largo para permitir que las ideas que se desarrollan en la parte posterior
de su mente. Esto no quiere decir que usted va a pasar ms tiempo en la documentacin. El plan justo para tomar un
descanso, y para hacer otras cosas en el medio, antes de completar un documento.
170 Gestin y Aseguramiento de la Calidad

A los efectos de documentacin, los miembros del equipo deben tener la oportunidad de retirarse
a su propia o fi cina, sin ser molestado por los otros miembros del equipo o clientes.

Figura 47 se expande en la idea de que la documentacin puede convertirse en un medio de validacin. En


un estilo similar al de diagramas de secuencia UML, con el tiempo fl debido de arriba a abajo, el diagrama
muestra cmo la los procesos de documentacin de diseo y evolucionan para producir sus resultados final.
Documentacin, que consiste en la escritura y la reflexin, se lleva a cabo a intervalos regulares, y
materiales de retroalimentacin para el proceso de diseo, que contina sin interrupcin.

Discusin En la mayora de los proyectos que es conveniente reservar marcos de tiempo regulares para la documentacin
y reflexin. Una idea es pasar cuatro das a la semana, el diseo, codificacin, teniendo reuniones y discusiones,
tal vez trabajando en las instalaciones del cliente, sino para reservar un da por semana para la documentacin y
reflexin en un ambiente ms tranquilo. una poltica de este tipo permite CONTINUACIN DE DOCUMENTACIN.

Dado que la documentacin es Una actividad distinta, su presupuesto y la prioridad puede ser alto o bajo,
dependiendo del proyecto, por lo que la regla de "cuatro das frente a un solo da de no siempre podran ser
apropiadas. En muchos casos, sin embargo, representa un equilibrio entre definen el desarrollo de software,
por un lado, y la documentacin y reflexin sobre la otra.

Por ltimo, la necesidad de un entorno tranquilo no significa que usted debe escribir la documentacin de
forma aislada. Slo una adecuada CULTURA REVISIN permite llevar a cabo una REVISIN antes de la entrega entre
el equipo, o una CRTICA DE CONSUMIDOR,
que le da la informacin necesaria de los dems.

revisin Cultura
Problema Cmo se puede mejorar la calidad de los documentos del proyecto?

Efectivo Casi nadie se las arregla para escribir buenos documentos sin la ayuda de otros. Esto es mucho pedir - nadie es tan
inteligente. Documentos necesitan una revisin, al igual que las necesidades de software de prueba.

Por desgracia, muchos de los comentarios mencionan solamente lo que le pasa a un documento, mientras que las
cosas buenas pasan desapercibidos. Las personas son, en diversos grados, con miedo a la crtica, y los autores a
veces se sienten reacios a han revisado sus documentos. Puede ser que tenga miedo de que su trabajo se considera
defectuosa cuando se presenta ante los ojos pequeos y brillantes de los crticos, o puede ser que tenga miedo de la
extra de
revisin Cultura 171

escritura reflexin

de entrada para la sujetos a La


documentacin reflexin

validacin

sujetos a La
reflexin

validacin

de entrada para la

documentacin
documentos para la documentacin

final de diseo fi nal de entrada de

Figura 47. Documentacin como un medio de diseo de validacin

esfuerzo de incorporar la retroalimentacin en su trabajo. Los comentarios pueden ser complicado, por lo que es importante
hallar maneras de hacer comentarios una experiencia positiva tanto para el autor como para los colaboradores.

La mayora de la gente acepta la crtica mucho mejor si est claro que la crtica est destinada a ayudar, no para
ponerlos abajo. Para lograr este objetivo, una revisin no debe ser restringida a la retroalimentacin negativa,
sino que tambin debe tener efectos positivos
172 Gestin y Aseguramiento de la Calidad

comentarios que hacer, y la revisin deben ofrecer sugerencias concretas de mejora, junto con sus
observaciones crticas (Coplien 2000). Adems de este problema psicolgico, tambin hay un punto de
vista prctico que sugiere que la revisin debe incluir la retroalimentacin tanto positiva como negativa. Los
autores son a veces inseguro sobre si mantener o reemplazar el material especfico. Sugerencias para
cualquiera de los enfoques - mantener o reemplazar - pueden ser tiles. Pero cuando una revisin no
menciona lo que es bueno, el autor podra terminar material que realmente debera haber sido dejado
como estaba reemplazando. Una revisin de todo negativo deja el autor en la oscuridad y no es muy til.

Solucin La documentacin puede bene fi cio muchos de los comentarios, siempre una cultura opinin se ha
establecido en la cual ambos autores y los colaboradores se sientan cmodos.

Una cultura crtica positiva requiere lo siguiente:

Los miembros del equipo deben estar dispuestos a discutir el material y proporcionar informacin cuando
se requiere su experiencia. Ellos deben entender su papel como uno de proporcionar un servicio al autor.

Los revisores deben obligan a ser honesto y deben llegar a los comentarios claras acerca de
la calidad del material. Deben mencionan tanto lo que sienten es bueno sobre el documento y
debe mantenerse, y lo que sienten no es tan bueno y lo que necesita mejorar.

Junto con los comentarios crticos, los revisores deben hacer sugerencias concretas para la mejora
siempre que sea posible.

Los miembros del equipo que ofrecen retroalimentacin deben recibir el reconocimiento y el crdito que se
merecen.

Los autores deben estar dispuestos a aceptar la retroalimentacin, sabiendo que las votaciones les
permitir escribir una mucho mejor documento.

Cuando otro documento est escrito, colegas pueden optar por cambiar mutuamente los
papeles de autor y revisor.

Un espritu de equipo positivo, a menudo apoyado en eventos sociales o actividades o fi cina-out ofof casuales,
ayuda a los miembros del equipo a entender que todos estn en el mismo barco. Esto no slo es cierto para la
documentacin, es cierto para todas las tareas del proyecto, y la documentacin no es una excepcin.
revisin Cultura 173

Discusin cultura opinin, el trabajo en equipo y, en general, ha sido objeto de mucha atencin en la
literatura.

Varios libros que ponen el nfasis en temas humanos en la computacin reconocen la importancia del
trabajo en equipo en todos los aspectos del desarrollo de software. Gerald Weinberg, en su libro sobre La
psicologa de la programacin informtica,
habla de la programacin 'ego-menos' (Weinberg, 1998). Frederick Brooks, en El mes laboral mtico, ( Brooks
1995), y Tom DeMarco y Timothy Lister peopleware ( DeMarco Lister 1987), tambin proporcionan un
montn de penetracin en el trabajo en equipo.

El trabajo en equipo, revisin, reflexin y retroalimentacin tambin juegan un papel muy importante en el
mundo gil. El manifiesto gil, en una de sus recomendaciones concretas, sugiere que a intervalos regulares
equipos reflexionar sobre cmo pueden ser ms eficaces, a continuacin, ajustar y adaptar su
comportamiento en consecuencia (Cockburn 2001). Varios mtodos giles ms detalles sobre esto (Cockburn
2001, Ambler 2002, Schwaber Beedle 2001). Norman Kerth, en su libro Retrospectivas de proyectos, describe
en detalle lo que las reuniones de reflexin pueden ser como, y da muchos ejemplos (Kerth 2001). Neil
Harrison Los patrones de organizacin para equipos ( Harrison 1996) hacen hincapi en la importancia del
espritu de equipo para todas las actividades del equipo. UN La unidad de propsito - compartiendo un objetivo
comn - es crucial para un equipo para trabajar bien juntos. En su libro Talleres de escritura, Richard Gabriel
describe una cultura resea que sea muy comn entre los autores de la prosa y la poesa, y que ha sido
adoptado por la comunidad para la revisin de los patrones de patrones de software (Gabriel, 2002). Un taller
de escritores es un evento especficamente diseado para permitir a los autores dan unos a otros
retroalimentacin intensa en su trabajo. Jim Coplien ha descrito esta cultura en su opinin Idioma patrn para
talleres de escritura ( Coplien 2000). Afirma que los autores y los colaboradores deben formar una Comunidad
de confianza en el que los comentarios crticos son tiles, en lugar de causar irritacin. Jim Coplien pide que,
para la crtica sea til en la prctica, concreta Sugerencias para mejorar se ofrece con cada comentario crtico.
Tambin hace hincapi en la importancia de tener Comentarios positivos En primer lugar, ya que por razones
psicolgicas, comentarios crticos son ms fcilmente aceptadas despus se ha proporcionado
retroalimentacin positiva.

Ninguna de estas ideas sobre el trabajo en equipo se aplica exclusivamente a la documentacin. La mayora de las
ideas se aplican al desarrollo de software en general, mientras que la
174 Gestin y Aseguramiento de la Calidad

ideas para los talleres de escritura son, dentro del contexto de la ingeniera de software, dirigidos
principalmente hacia la discusin de los patrones de software. Sin embargo, lo que todas las personas
mencionadas anteriormente tena en mente cuando escribi sobre el trabajo en equipo fue capacitar a los
equipos a colaborar en un objetivo comn. Esto es algo de lo que la documentacin puede tambin pro fi t.

Revisin Antes de entrega


Problema Cmo pueden los autores recibir la retroalimentacin adecuada en el momento adecuado?

Efectivo Sabemos que los documentos deben ser revisados. Sin embargo, tambin sabemos que los exmenes utilizan
recursos, y que los comentarios innecesarios deben ser evitados por razones econmicas. En qu medida
son necesarios exmenes? Esto depende de varios factores. En primer lugar, la familiaridad del autor con el
tema, y la experiencia de la escritura del autor, ambos tienen una influencia en la cantidad que se necesita una
revisin.

A continuacin, el estado del documento juega un papel importante. Los documentos que describen el
trabajo en curso no se puede esperar que sea perfecto, ya que se sometern a cambio. Es perfectamente
aceptable para hacer circular dichos documentos entre colegas que entienden que son los documentos
preliminares. Fi ciales de revisin para las versiones preliminares no tienen sentido. No obstante, los
comentarios sobre una versin preliminar puede ayudar a formar el alcance y la estructura general de un
documento desde el principio.

En algn momento, sin embargo, son los documentos o fi cialmente distribuida - tal vez slo en el equipo, o tal
vez para el cliente, con una versin de software. Estos documentos deben cumplir con los estndares ms altos
de calidad.

Solucin Las primeras crticas son definir, ya que ayudan al autor a determinar el alcance y la estructura de un
documento. Pero antes de que un documento es de fi cialmente distribuye o entrega al cliente, una
revisin es obligatoria.

Slo el autor puede decidir en qu medida temprana o intermedia comentarios son tiles. En la mayora de los casos
una revisin informal es su fi ciente para dar el autor retroalimentacin temprana.

El examen final no es tema de debate. Como regla general, ningn documento debe ser puesto en libertad
a los lectores no involucrados hasta que haya pasado un examen final.
Crtica de consumidor 175

Esta revisin debera tener lugar mucho antes de la fecha prevista de la distribucin del documento, para
dar tiempo a las revisiones, y debe responder a las siguientes preguntas:

El documento cumple con sus objetivos, y ser de utilidad para los lectores?

Es el documento tcnicamente precisa, y tampoco proporciona el nivel adecuado de detalle tcnico?

Es la estructura y organizacin general verdad?

El documento proporciona suficientes ejemplos para ser comprensible?

Qu pasa con el diseo y el lenguaje?

Discusin Los comentarios no ocurren automticamente. Es responsabilidad del documento de


UNO autor responsable para asegurarse de que los exmenes se llevan a cabo y para asegurar que las votaciones
se incorpora.

Obviamente, el autor responsable puede estar en desacuerdo con lo que dice un revisor o revisores diferentes
puede tener opiniones conflictivas. En ltima instancia, el autor responsable no slo tiene que procurar que las
votaciones se incorpora, pero tambin es libre de decidir cmo las votaciones se incorpora. La necesidad de este
patrn se deriva en gran parte de la idea de CONTINUACIN DE DOCUMENTACIN. En las primeras etapas de un proyecto
que es demasiado pronto para revisar los detalles de cualquier documento. A medida que la fecha de lanzamiento
para el software que se acerca y un documento que se supone que debe ser completado, esto tambin es el
momento de planificar la revisin final.

Los comentarios se refieren principalmente a los contenidos de un documento. Adems, los colaboradores pueden
comprobar la calidad de la presentacin. Especialmente, se pueden examinar qu tan bien un documento aborda
la A quin va destinado, lo bien que se presenta
CENTRADO INFORMACIN, y la calidad de Ejemplos realista.

Crtica de consumidor

Problema Cmo puede utilizar un equipo de documentacin para aumentar la implicacin del cliente?

Efectivo En cualquier proyecto es el equipo, y no el cliente, que est a cargo. El equipo se espera que produzca

resultados, y la documentacin no es una excepcin. Los equipos son, por tanto, inclinados a progresar

rpidamente, por lo que tienen resultados que pueden ofrecer. Sin embargo, la implicacin del cliente es

necesario. En primer lugar, el proyecto


176 Gestin y Aseguramiento de la Calidad

actores estn interesados en cmo est progresando el proyecto, y su participacin es una manera de
mantenerlos informados. En segundo lugar, el cliente es informado con claridad, especialmente en el
dominio de la aplicacin, y puede contribuir mucho a hacer el proyecto ms exitoso.

La documentacin es un rea donde los clientes pueden estar involucrados. La entrega de la


documentacin a los grupos de inters es una forma de mostrarles hacia dnde se dirige el proyecto. Por
otro lado, el cliente tambin puede proporcionar informacin valiosa sobre la documentacin.

Todo esto se puede resumir diciendo que la mejor es la colaboracin con el cliente, mejor son las
posibilidades de xito del proyecto.

Solucin Comentarios de los lectores pueden mejorar la calidad de un documento, especialmente en lo que se
refiere a la experiencia en el campo, y al mismo tiempo aadir a la formacin de equipos y la integracin.

Las siguientes pautas ayudan a hacer revisin del cliente con xito:

El cliente debe ser consciente de que el documento que se examina es un borrador. El documento
debe decir claramente que s, porque de lo contrario puede ser confundido con un documento final,
pero mal hecho fi.

Un proyecto no debe ser demasiado tentativo. Como miembro del equipo, no se puede esperar que el cliente
haga su trabajo y su vez una coleccin de materias primas en un documento para usted.

Una revisin del cliente puede generar importantes discusiones, y puede contribuir mucho a hacer un
proyecto de un esfuerzo conjunto en el que el equipo y el cliente trabajan juntos hacia un objetivo
comn.

Discusin Colaboracin con el cliente es uno de los valores fundamentales del manifiesto gil. Se ha enfatizado
mucho en la literatura sobre el desarrollo gil, y ms generalmente en la literatura sobre el trabajo en
equipo eficaz de los proyectos. Por ejemplo, Jim Coplien, en su Desarrollo generativo-Proceso lengua
del patrn ( Coplien 1995), recomienda que los proyectos Atraer a los clientes, especialmente, aunque
no exclusivamente, para fines de control de calidad. En su Patrones de interaccin con el cliente, Linda
Rising discute este tema en detalle (2000a Rising). Entre otras cosas, se recomienda que los equipos
aprenden a Conocer al cliente, y que se Escuchar, escuchar, escuchar a lo que dice el cliente. Tener los
conceptos documentados revisados por el cliente contribuye claramente a la colaboracin con el
cliente desee.
Una vista distante 177

Para una revisin del cliente para trabajar sin problemas, el equipo y el cliente tienen que establecer una CULTURA
REVISIN en el que dichas revisiones se considera normal, y en la que ningn miembro del equipo tiene
razones para sentirse ofendido por las crticas. El cliente debe reconocer la necesidad del equipo para la
retroalimentacin, y no debe culpar al equipo por no ser expertos en el dominio de aplicacin. El cliente
debe entender que la solicitud de revisin es una manera de asegurar la calidad de los resultados del
proyecto.

Una vista distante


Problema Cmo pueden los autores obtengan retroalimentacin imparcial?

Efectivo Los colaboradores que estn muy familiarizados con un documento en revisin son propensos a tener una
visin algo sesgada. Puede ser que tome un montn de cosas por sentado que podran ser interrogados
por un revisor imparcial, y por lo tanto pueden no llegar a una evaluacin fiable.

Este suele ser el caso cuando los miembros del equipo actan como colaboradores. En general, se definen para
tener la documentacin del proyecto los miembros del equipo de revisin, pero a veces son tan inmerso en el
proyecto que se toman los fundamentos del proyecto por sentado. Lo que parece ser evidente para el equipo
todava puede ser sofisticado para los no expertos.

Por otra parte, los documentos del proyecto son a menudo revisados por personas con formacin tcnica. Estos
revisores tienden a centrarse en el contenido tcnico de un documento pero pasan por alto los problemas de
presentacin. Sin embargo, la calidad de la presentacin tambin merece atencin.

Solucin Los autores pueden obtener retroalimentacin imparcial de los colaboradores que estn interesados en
el tema y que por lo general tienen conocimiento en el campo, pero que no estn involucrados en el
trabajo real se describe en el documento.

Los buenos candidatos para una revisin lejana visin son:

Alguien desde fuera del equipo que est familiarizado con el dominio de aplicacin.

El cliente, que a menudo puede tomar una perspectiva ligeramente diferente.

En menor grado, un crtico desde el interior del equipo con un nivel educativo diferente.
178 Gestin y Aseguramiento de la Calidad

Normalmente estas personas no van a centrarse en los detalles tcnicos en sus opiniones - y, de hecho,
en realidad no debera. Ms bien, es su trabajo para comentar sobre la estructura global de un
documento, su general 'cuadro grande' y de si sienten que el documento se refiere en general los temas
correctos.

Discusin En realidad hay dos tipos de comentarios que se complementan entre s. Para los beneficios de una CULTURA
REVISIN materializarse plenamente, es necesaria la retroalimentacin a diferentes niveles. Por un lado,
colegas cercanos que estn familiarizados con el material presentado puede proporcionar comentarios tiles
en un nivel ms tcnico. Por otro lado, la gente de fuera del equipo, tal vez el A quin va destinado, puede tener
una visin lejana y proporcionar valiosos comentarios de alto nivel. Si es el cliente que toma la vista lejana,
mantener los lineamientos para una CRTICA DE CONSUMIDOR en mente.

La recomendacin de poner a alguien de fuera del equipo se encuentra comnmente en la literatura. En


su Desarrollo generativo-Proceso lengua del patrn ( Coplien 1995), Jim Coplien se ocupa de la cuestin
de las revisiones de diseo. Se sugiere la contratacin de una analista mercenaria desde fuera del equipo
que es un experto en el dominio y que puede proporcionar retroalimentacin. Este es un principio
importante, no slo para las revisiones de diseo, sino tambin los exmenes de proyectos de
documentacin. En el Creador-Crtico patrn de la Las pautas de diseo de equipos

(Weir, 1997), Charles Weir explica que el conocimiento detallado del dominio de aplicacin es un requisito
importante para un revisor. Tambin recomienda que los colaboradores no estar involucrados en el trabajo
que se examina.

Por ltimo, este modelo tambin corresponde a una observacin descrito en Neil Harrison Los
patrones de organizacin para equipos ( Harrison 1996). Diversidad de los miembros estados que
mezclaban Equipos - equipos con personas de diferentes edades y sexo, as como con los diferentes
niveles educativos y culturales - por lo general funcionan mejor que los equipos ms homogneas, ya
que los miembros del equipo se complementan entre s. En lo que se refiere al proceso de revisin, la
mejor retroalimentacin se puede esperar de los colaboradores de distintos orgenes, tanto el uno al
otro y al autor.
informacin del mercado 179

informacin del mercado


Problema Cmo se pueden prevenir buenos documentos de ir tristemente inadvertido?

Efectivo La produccin de documentos por s sola no es suficiente. El mejor documento en el mundo no vale
mucho si no llega a los lectores previstos. No hay ningn punto en la realizacin de un documento,
ponindolo en los archivos ya la espera de otros miembros del equipo que vienen a travs de ella. Esta
sera la estrategia correcta slo si todo lo que destinados a un documento era utilizarlo como excusa
cuando el proyecto va por mal camino, por ejemplo, como argumentar: 'Este no es mi culpa, he
documentado todo' Tal actitud es exactamente lo contrario de ser gil. En un contexto gil, no queremos
que los documentos del proyecto para que sirvan como excusas, queremos que facilitan la comunicacin
entre el equipo. Esto significa que tenemos que abordar activamente los miembros del equipo y hacerles
saber que no es un documento que les podra ayudar con su trabajo.

S, hay opciones tcnicas para hacer documentos fcilmente disponibles, y hay maneras de
tcnicas para distribuir documentos entre un equipo. Es definir de usar estas posibilidades, y son el
primer paso para hacer la documentacin de un medio eficaz de comunicacin. Pero puede tomar
un importante segundo paso al atender directamente los lectores previstos.

Solucin Documentos ganan ms atencin si los presuntos lectores estn invitados activamente para
leerlos.

Hay diferentes maneras en que puede acercarse a otros miembros del equipo cuando un documento
importante ha sido terminado y est siendo puesto a disposicin:

Se puede mencionar el documento en una reunin de equipo, dar una breve introduccin a lo que dice el
documento e invitar al equipo a ponerse en contacto con usted siempre que las preguntas siguen sin
respuesta.

Puedes fijar una copia impresa en el tabln de anuncios del proyecto.

Puede enviar un mensaje de correo electrnico breve al equipo en el que se explica el propsito del
documento y dnde se puede encontrar. En cualquier caso, la documentacin per fi cios en gran medida de una
atmsfera en la que la informacin se intercambia libremente, y en el que las personas que los dems sepan de
cualquier documento que les podra ayudar.

Discusin Este patrn parece similar a la idea de dejar que sus colegas sabe de una nueva versin a travs de
una NOTIFICACIN EN ACTUALIZACIN. El nfasis de este patrn,
180 Gestin y Aseguramiento de la Calidad

Sin embargo, no es en ningn tipo de soporte tcnico, sino ms bien en las personas toman actitud
hacia la documentacin. Este patrn nos recuerda que, cuando hemos completado un documento, se
supone que debemos llevar el documento a la
OBJETIVO Lectores.

Una de las opciones de implementacin para este patrn - fijando un documento importante para el tabln de
anuncios del proyecto - est estrechamente relacionado con lo que Alistair Cockburn llama una 'informacin del
radiador'. En Desarrollo gil de Software, sugiere que cada proyecto utiliza un radiador de informacin que
muestra informacin en un lugar donde los transentes pueden verlo (Cockburn 2001). Si un equipo se utiliza
para la comunicacin electrnica, tambin se puede optar por poner el documento en el proyecto WIKI y se
adhieren a ella un mensaje a todos los miembros del equipo para ver. La adopcin de una cultura de intercambio
de informacin gratuita en proyectos allana el camino para una actitud gil hacia el tratamiento de la informacin
ms all de los proyectos. Si consideramos la documentacin como algo que se distribuye de forma activa, nos
encontramos con la condicin previa para el xito, en toda la organizacin Gestin del conocimiento.

Gestin del conocimiento


Problema Cmo pueden los proyectos futuros bene fi cio de un proyecto exitoso?

Efectivo No hay dos proyectos iguales. Sin embargo, los proyectos tienen cosas en comn. Hay analogas y
similitudes. Todos hemos estado en situaciones en las que tuvimos que encontrar una solucin a un
problema, muy consciente de que los dems deben haber resuelto un problema similar antes. Si tan slo
pudiramos aprender sobre su solucin, podramos ahorrar tiempo y esfuerzo.

Casi todos los proyectos pueden bene fi ciarse de la experiencia adquirida en proyectos anteriores. Pero podemos
sacar de esta experiencia slo si se pone a disposicin dentro de la organizacin. La documentacin es una manera de
hacer esto, ya que compromete la experiencia para el papel y lo guarda para su uso futuro.

Sin embargo, incluso el mejor documentacin no es til si nadie sabe que existe, o nadie tiene acceso a ella. Con
demasiada frecuencia, los nuevos proyectos de re-inventar cosas, no porque los proyectos anteriores no
documentaron ellos, sino porque las personas no son conscientes de que la informacin est disponible.
Gestin del conocimiento 181

Solucin Slo cuando la documentacin del proyecto se pone a disposicin de toda la organizacin hacer proyectos de
futuro tienen la oportunidad de aprovechar la experiencia adquirida.

Esto tiene tanto una tcnica y un aspecto cultural:

Hacer la documentacin disponible requiere algn tipo de sistema de gestin del conocimiento,
como se ilustra en la Figura 48. Tal vez esto es una gua accesible al pblico, tal vez es una
intranet.

proyecto E

proyecto D

proyecto C

proyecto B

Un proyecto base de conocimientos

Figura 48. Extraccin de conocimiento y transmitirla


182 Gestin y Aseguramiento de la Calidad

El aspecto cultural es ms importante. El uso de documentacin para la gestin del conocimiento


puede ser til slo en una cultura que anima a la gente a compartir sus experiencias. La
comunicacin informal juega un papel muy importante aqu. Como un miembro del proyecto,
informe a los colegas que existe la documentacin. Invitar a la gente para examinarlo y para
volver a usted si tienen preguntas. Que quede claro que hay una posibilidad de que otros puedan
bene fi cio de su trabajo.

Discusin Tcnicamente, lo que sugiere que este patrn es la integracin del proyecto de DOCUMENTO PAISAJE en
un paisaje de documentos que son relevantes para toda la organizacin. Si utiliza una intranet esto
es particularmente fcil, convirtiendo su proyecto WIKI en una casa en WIKI.

Aqu es donde se cierra el ciclo de documentacin. Usted ha estado ocupado haciendo


CONTINUO DOCUMENTACIN a travs de su proyecto, que ha pasado por etapas de Y ESCRITURA REFLEXIN,
y el CULTURA REVISIN que ha permitido a fi nes de los conocimientos de sus colegas.

Ahora la experiencia que ha adquirido puede ser til para los dems. Esto es cierto en particular para el
material que se coloca una Centrarse en la pertinencia de largo plazo,
tales como documentos de transporte EL PANORAMA de la arquitectura, o la
DISEO RAZN FUNDAMENTAL.

En este punto, se ha producido una serie de documentos en su proyecto. No debera haber


demasiados de ellos. Los patrones anteriores de este libro le han guiado a un enfoque en los
temas correctos, y para hacer la documentacin bien organizada y ligero. Ahora usted y otros
pueden bene fi ciarse de trabajo que se hizo. Esta es la idea de la documentacin gil.

Informes de experiencia
Me gustara concluir este captulo con mediante el examen de los procesos de documentacin en varios
proyectos de ejemplo, y cmo estos procesos cumpli o no cumpli con los patrones en este captulo.

Procesos y El manifiesto gil favorece a los individuos e interacciones sobre procesos y herramientas, y respondiendo a

planes cambiar con el seguimiento de un plan. Una vez ms, el manifiesto no niega el valor de los procesos y
planes. Pero nos advierte que no debemos seguir un plan por el bien del plan.
Informes de experiencia 183

Proyecto persistor da un buen ejemplo de lo que es un proceso de documentacin de peso ligero puede ser
similar. El equipo era consciente de que un cierto grado de documentacin fue crucial para el xito del
proyecto, considerado como la documentacin UN ACTIVIDAD DISTINCT, e incluido las tareas de documentacin en
la lista de las actividades del proyecto, como se muestra en la Figura 50.

30% 15 % 50% 15 %

Documentacin
Especificacin Diseo Codificacin pruebas

Figura 49. Proyecto persistor: se espera presupuesto de documentacin en un proyecto de desarrollo

Paquetes de trabajo para la liberacin 5.0

No. Paquete Presupuesto Prioridad Observacin Responsable Lanzamiento

1 funcionalidad

1.1 Manual de desbloqueo 2 do RS claro si realmente se necesita 5.0

verificacin de tipos 1.2 API 5 segundo Alaska 5.0


1.3 La mejora de los cdigos de error UN

2 pruebas

2.1 Los casos de prueba para mecanismos de cach 2 UN RS 5.0


2.2 los pilotos de pruebas de Java para todos los casos de uso 5 UN CW 5.0
3 Actuacin
mecanismos de ajuste 3.1 Rendimiento 20 segundo RS 5.0 o posterior

4 Documentacin

4.1 concepto de uso: describir una funcionalidad adicional 2 UN Arkansas 5.0


concepto 4.2 Uso: aadir ejemplo para el modelo de estado 1 UN Arkansas 5.0
4.3 Concepto de diseo: actualizaciones 5 do 5.0 o posterior

5 Entrenamiento

5.1 Taller 2000-05-25 5 UN Arkansas

Figura 50. Proyecto persistor: hoja de planificacin del proyecto, incluyendo tareas de documentacin
184 Gestin y Aseguramiento de la Calidad

Proyecto persistor: documentacin como una tarea normal de proyecto

El equipo se reuni con regularidad para reuniones de estado breves en las que se discutieron los pasos a seguir. La documentacin
se trat en estas reuniones, al igual que todas las dems tareas del proyecto. Al principio, el proyecto tena de fi nen ciertos
documentos que tenan que ser por escrito, y se haba decidido sobre algunos documentos adicionales ms adelante. Durante las
reuniones regulares del equipo comprueba el estado de los documentos y lo que an haba que hacer.

Los documentos se consideraron artefactos del proyecto al igual que el cdigo, casos de prueba y as sucesivamente. Para cada
documento de una persona que estaba a cargo. Cada documento cont con un presupuesto que podra extenderse en la demanda y si es
necesario, pero estaba claro desde el principio del tiempo aproximado que el proyecto estaba dispuesto a gastar en cada documento. La
Figura 50 muestra un extracto de la hoja de planificacin del proyecto.

Cmo manejar el equipo para estimar el esfuerzo que era necesario para la documentacin? Esto se realiza principalmente sobre
la base de la experiencia. La figura 49 muestra cmo, en esta organizacin, el esfuerzo de desarrollo se distribuye normalmente
durante las diferentes etapas de un proyecto, basado en la experiencia de proyectos anteriores (Siedersleben 2003). La figura 49
muestra tambin cmo gran parte del esfuerzo que el equipo espera que entre en la documentacin - proporcionalmente ms en la
fase de especi fi cacin, pero disminuye a partir de entonces. El porcentaje de la documentacin puede parecer bastante alto, y de
hecho es ms pequea en muchos proyectos, pero el hecho de que el equipo se va a construir un marco requiere el uso de un
concepto integral, y esto fi justificado un esfuerzo ms grande para la documentacin.

Las personas que escribieron los documentos aprendido mucho en el proceso. Por ejemplo, por escrito concepto de uso
del marco oblig a los desarrolladores de marco para ver su marco de un punto de vista diferente. Los autores obtuvieron
una idea de su propio sistema durante la escritura. Cometer un concepto claro sobre el papel de cmo aplicar el marco en
casos prcticos los obligaron a reflexionar sobre cuestiones que haban pasado desapercibidos en las discusiones de
diseo, y que tal vez haban dado por sentado.

Por desgracia, el documento de diseo no se manej tan bien. El documento de diseo perdi la atencin del equipo cuando el
equipo se volvi muy ocupado con otras cosas. El problema no era que las actualizaciones de este documento se retras, fue
que a partir de un cierto punto en el que nadie se senta responsable del documento, por lo que las actualizaciones necesarias
que nunca se hicieron. Diferentes personas aaden material, pero de forma no coordinada. El documento termin inconsistentes
y anticuado, proporcionando algunas ideas de diseo pero que carecen de la motivacin detrs del diseo y las ventajas y
desventajas de los diferentes enfoques que se haban examinado. Este documento no sirvi su propsito muy bien.
Informes de experiencia 185

El equipo decidi que la documentacin era necesaria y ajustar sus decisiones con regularidad. En
general, este proceso funcion bastante bien. La documentacin en su totalidad se descompone en
paquetes manejables, y cada documento tenido UNO autor responsable y un plazo que permita una

REVISIN antes de la entrega.

La documentacin del proyecto persistor enfrenta un gran problema, sin embargo. A pesar de que haba
comenzado como CONTINUO DOCUMENTACIN, cambios a la documentacin ms tarde fueron descuidados
cuando los plazos dibujaron la actividad ms y animado situado en. Como consecuencia de ello, la exactitud
de los documentos sufri. En lugar de describir cmo el diseo del marco haba evolucionado y por qu, todo
el documento de diseo del mencionado fueron las ideas de diseo que el equipo haba tenido al comienzo
del proyecto.

Esto no fue un gran problema al principio, pero el equipo pagado por estas deficiencias dos aos ms
tarde, cuando una refactorizacin importante fue necesario, ya que la
DISEO RAZN FUNDAMENTAL no estaba disponible. (Vase tambin el informe del proyecto en el Captulo 1,

Proyecto persistor: di fi cultades con las nuevas exigencias, pgina 58.) Browsing documentos obsoletos, el
equipo tuvo dificultades para trabajar a cabo el razonamiento detrs de los cambios de diseo realizados
durante los ltimos dos aos, y se qued atascado en un callejn sin salida ya explorados por sus colegas.

Creo que la importante conclusin a extraer de esta experiencia es que en cuanto a la actualizacin de los
documentos se refiere, no se puede esperar hasta que realmente se necesita una versin exacta. Este es el
momento en el que ya es demasiado tarde. Con bastante frecuencia, las actualizaciones de la documentacin no
son lo ms urgente un proyecto tiene que ver. Pero no hay que confundir urgente con importante. Esperar un poco
para actualizaciones de la documentacin puede ser justificado - simplemente no espere a que los expertos han
dejado el proyecto o estn ocupados con otras cosas.

Las experiencias de Proyecto Vista copia de seguridad de este punto de vista (pgina 186). El hecho de
que este proyecto lleva a cabo CONTINUO DOCUMENTACIN fue la clave de su xito. No es que el entorno de
las aplicaciones que produca era precisa todo el tiempo - no lo era. Pero a medida que el equipo
aprendi ms y ms sobre las aplicaciones en la organizacin del cliente y cmo se interrelacionan, se
actualiza el entorno de las aplicaciones, que siempre refleja el conocimiento actual y reiter hacia una
descripcin exacta.

En lo que se refiere a la planificacin de la documentacin, hay que tener tambin en OpenDoors proyecto.
La documentacin de este proyecto careca EL PANORAMA, y los documentos que se solapan no hicieron
exactamente presente INFORMA- ENFOCADO
186 Gestin y Aseguramiento de la Calidad

Proyecto Vista: actualizaciones regulares al entorno de las aplicaciones

El diagrama con el entorno de las aplicaciones (Figura 7, pgina 54) se actualiza despus de cada entrevista, el equipo
de consultora tuvo con el cliente. De esta manera, el esquema siempre reflejaba el conocimiento actual del equipo
tena del entorno de las aplicaciones que han sido analizar.

Esto era importante, ya que el diagrama se utiliza regularmente en entrevistas para obtener las discusiones iniciadas. Se le ha
dado a varios representantes de los clientes, que les pidi que comentaran sobre el mismo, y para agregar las aplicaciones que
conocan, as como las dependencias entre aplicaciones. Al mantener el diagrama hasta la fecha, el equipo podra asegurarse
de que cada entrevista trajo una perspectiva adicional.

Debido a que el esquema haba sido utilizado con xito durante el proyecto, el equipo consider que una tcnica similar
podra ser utilizado en otros proyectos tambin. El diagrama de aplicacin paisaje se present al personal general de la
compaa de software en un artculo que apareci en la empresa revista trimestral de la casa. En este artculo se introdujo
brevemente el proyecto, y explic el papel del diagrama haba jugado en la especi fi cacin del entorno de las aplicaciones.
Por otra parte, la especificacin (que consista en esencia, que el diagrama) se convirti en parte del depsito de
documentos de ejemplo para proyectos de consultora de la compaa de software.

CIN. ( Vase tambin el informe del proyecto en el Captulo 1, OpenDoors del proyecto: la comunicacin, el
diseo la pgina 55.) Esto se debi principalmente a un problema con la gestin de la documentacin en
este proyecto: la mayor parte de los documentos no tenan UNO Autor responsable. En lugar de ello, diferentes
personas aaden material a la documentacin del proyecto de una manera bastante descoordinada. La
superposicin de documentos e informacin inconsistente fueron la consecuencia, as como un esfuerzo
innecesario pasado en demasiados documentos. Fue no slo los documentos que se superponen. La
documentacin refleja las ideas de diseo que se solapan e inconsistentes que estuvieron representados
en la arquitectura del portal Web.

Las cosas cambiaron para mejor cuando se produjo un importante refactorizacin. No slo fue
rediseado el software, los documentos eran as. Esto podra ocurrir slo porque en esta etapa de la
documentacin se consider Una actividad distinta.
Los documentos refactorizado salido bien porque cada uno tena Un autor RESPONSABLE, que se preocupaba
por la calidad de la documentacin.

hacer circular En cuanto a los informes de los proyectos persistor, Vista y OpenDoors, nos damos cuenta de que la planificacin

documentos cuidadosa por s sola no es suficiente para producir la documentacin que sea til y que se utiliza. Los
documentos que se utilizaron en gran medida tienen en
Informes de experiencia 187

OpenDoors proyecto: hacer circular la documentacin para la retroalimentacin

Este proyecto consisti en muchos equipos. El equipo marco extendi un marco que proporciona la funcionalidad bsica
para el portal web del cliente. Otros equipos trabajaron en las aplicaciones que se van a integrarse en el portal. Debido a
que muchos equipos estaban involucrados, y porque los equipos estaban bajo presiones de tiempo, los diseos de las
diferentes aplicaciones evolucionaron en direcciones ligeramente diferentes. La arquitectura general del portal web de
esta manera se convirti en algo inconsistente.

Curiosamente, no hubo un efecto similar en la documentacin. La documentacin fue un poco mal cuando un nmero de
personas trabaj en diferentes documentos conceptuales que abordaron los temas que se solapan. Algunos de estos
documentos se han actualizado, otros no, y como resultado se convirti en la documentacin inconsistente en algunos lugares.

En algn momento, los arquitectos decidieron que era hora de un refactorizacin, por lo que todas las aplicaciones
compartiran una arquitectura comn. Durante este refactorizacin, tambin se abord la documentacin. Un pequeo
grupo se hizo cargo de un nuevo conjunto de documentos que por una parte se describe la arquitectura general y los
principios de diseo, y por otro cmo se integraron las distintas aplicaciones y cmo se podra implementar en la Web.
Estos documentos se sometieron a un proceso de revisin informal. Informales, pero no lo era, le dio la gente de varios
departamentos de la oportunidad de compartir sus pensamientos. La documentacin fue revisado dentro del equipo de
marco y se distribuy entre los desarrolladores de aplicaciones, que incluyen muchos colegas de personal del cliente.

Debido a que los documentos conceptuales fueron distribuidos antes de la codificacin real, los equipos que se utilizan para las futuras
versiones del marco podra examinar estos conceptos con antelacin. Ellos aprendido acerca de lo que podan esperar, sino que
tambin tuvo la oportunidad de formular observaciones sobre los conceptos de diseo. Varios puntos dbiles fueron identificado como
muchas otras personas ofrecieron sus puntos de vista. Como resultado, se han mejorado tanto la arquitectura general y su
documentacin. Ms que eso, distribucin de los documentos y la peticin de evaluar contribuy a la sensacin de unidad entre todas
las partes implicadas: la compaa de tecnologas, un subcontratista y el cliente. Todo el mundo haba estado implicado, aunque de
diferentes maneras.

comn que se distribuyeron de forma activa entre el equipo y para el cliente.

Hay dos lados a esto. En primer lugar, puede distribuir un documento para una revisin. Un manifiesto CULTURA
REVISIN aade en gran medida a la participacin del cliente y permite a los equipos reciben mucha informacin
sobre lo que han escrito. Proyectos persistor y OpenDoors recibieron una gran cantidad de informacin til
cuando el docu- marco
188 Gestin y Aseguramiento de la Calidad

mentacin se pas a los usuarios del programa marco. Proyecto Vista aprendido mucho de discutir el
entorno de las aplicaciones y lo que an le faltaba a que muchas de las partes interesadas en la
organizacin del cliente. Ninguna de estas revisiones pas por un proceso de peso pesado, y el hecho de
que la burocracia podra evitarse contribuy en gran medida a los xitos de la revisin. Proyecto salir, sin
embargo, ofrece una advertencia. mientras que una CRTICA DE CONSUMIDOR puede ser extremadamente til,
debe quedar claro al cliente que el documento que se examina es de hecho un proyecto. Proyecto liberarse
entr en una situacin crtica cuando los documentos fueron distribuidos que no haban sido objeto de una REVISIN
antes de la entrega

y el cliente asume falsamente estos documentos eran definitivas.

Proyecto liberarse: problemas con el material sin revisar


En un momento dado, el equipo se le pidi hacer una versin provisional del documento de concepto de reingeniera
disponible. Este documento fue importante para el cliente, y dado que la relacin con el cliente era bueno, el equipo
accedi a entregar el documento preliminar a pesar de que no haba sido revisado internamente.

Por desgracia, debido a algunos malentendidos anteriores del dominio de aplicacin, el documento contena algunos errores
que no haban sido corregidas. Cuando este documento se distribuy a uno de los departamentos del cliente, varias personas
estaban molestos por estos errores, ya que consideraban que no se entendan. La versin del documento provisional haba
causado ms problemas que beneficios.

El equipo decidi que haran las futuras versiones disponibles slo despus de haber sido revisados internamente. Estas
revisiones internas nunca llegaron a ser los procedimientos burocrticos, pero se aseguraron que los errores graves en la
documentacin podra ser fijo antes de que pudieran causar vergenza innecesaria.

El segundo aspecto de la distribucin de los documentos es hacer hincapi en que todo el que escribe un
documento es la encargada de ponerse en contacto con el A quin va destinado.
No hay ningn punto en el almacenamiento de un documento en algn lugar, incluso en su lugar apropiado, y
esperar a que otros lo lean. Se pone de pie una mejor oportunidad de llegar a sus lectores si se comunica con
ellas de forma activa y crea una INFORMACIN mercado. En Proyecto persistor, el equipo invit a los usuarios del
programa marco por correo electrnico a mirar la documentacin antes de que se llevaron a cabo talleres.
OpenDoors proyecto distribuyen la descripcin de la arquitectura de forma activa entre el equipo. Proyecto
Vista tom una copia de su esquema de aplicacin horizontal a todas las reuniones.
Informes de experiencia 189

Obtener y Una buena razn para la produccin de un documento es proporcionar una oportunidad para pensar en un

preservar el tema a travs. Esto sucedi en el Proyecto persistor (ver el informe de la experiencia en la pgina 184). El
equipo haba tenido muchos debates pizarra, de la que haba surgido una buena idea de la arquitectura
conocimiento
general. Pero cuando el equipo comprometido sus ideas de diseo de papel, que se vieron obligados a
cavar ms profundo. Un proceso de ESCRITURA Y REFLEXIN les permiti piensan que sus ideas a travs de y
para comprobar posibles inconsistencias de datos. Documentacin permiti al equipo a definir con precisin
el diseo.

Mi experiencia es que este enfoque funciona mucho mejor para algunas personas que para otras. Algunas
personas tienen buenas ideas en frente de una pizarra, otros tienen excelentes ideas para la catalogacin. La
observacin es que las personas ms introvertidas tienden a ser ms creativos durante la escritura, mientras
que las personas ms extrovertidas ms a menudo que no prefiere trabajar con una pizarra. Dado que
algunas personas aprenden mucho durante un proceso de ESCRITURA y la reflexin, es aconsejable mantener esta
oportunidad.

Flexicar proyecto: mantener la experiencia dentro de la empresa


Los diseadores han elegido una arquitectura basada en un servidor de aplicaciones y el uso de EJB (Enterprise Java Beans)
para poner en prctica la programacin ptima de las etapas de produccin para la fabricacin de automviles. El documento
de diseo que describe esta arquitectura se desarroll junto con el software. El documento se mantuvo durante el curso del
proyecto, lo que garantiza que el software y la documentacin en realidad nunca sali de sincronizacin. Al mismo tiempo, los
usuarios del documento hicieron comentarios tanto en la descripcin del diseo actual y de lo que se ha descrito.

En el momento en que se complet el proyecto, el documento describe la arquitectura de diseo con mucha precisin,
incluyendo una discusin de los pros y los contras del enfoque tecnolgico elegido. En este punto, este documento se
convirti til ms all del proyecto real. El documento pas a formar parte del repositorio de la compaa para la
documentacin de diseo, de modo que otros proyectos en diferentes dominios de aplicacin podran bene fi cio de la
experiencia adquirida con los servidores de aplicaciones y EJB.

Una vez que hemos adquirido los conocimientos que es esencial para un proyecto, cmo tratar con l? El
conocimiento debe ser compartido entre el equipo. La documentacin es una manera de expresar el
conocimiento. La interaccin directa, por ejemplo a travs de discusiones y talleres, es otra. He mencionado
antes que una combinacin de ambos es la mejor estrategia para hacer de la sabidura colectiva de un
equipo a disposicin de todos los miembros. Cuanto ms se ofrece activamente el proyecto de docu-
190 Gestin y Aseguramiento de la Calidad

mentos a la audiencia prevista en una INFORMACIN mercado, cuanto ms se llega a sus lectores.

El papel de la documentacin no se limita a los proyectos individuales, sin embargo. Alistair Cockburn
menciona que una funcin importante de la documentacin es 'prepararse para el siguiente juego'
(Cockburn 2001). As que hay que identificar los documentos que pueden ser tiles ms all de los lmites
de su proyecto actual, y hacer los documentos ms ampliamente disponible.

Varios informes de proyectos dan ejemplos de cmo se puede hacer esto. Los proyectos Flexicar, AirView y
persistor todos contribuyeron a base de conocimientos de la compaa de software - una piscina de informacin
basada en la Web que aloja documentos conceptuales ejemplares y los informes de la experiencia de proyectos
anteriores.

Proyecto AirView: hacer que el conocimiento en el diseo de interfaz grfica de usuario disponibles

Este proyecto fue nico en el sentido de que se centra tanto en el diseo de interfaz grfica de usuario. El diseo involucrado aspectos
ergonmicos que no se encuentran normalmente en los proyectos tpicos de la compaa de software.

La empresa mantiene un repositorio de xito especificaciones y diseos que se originan de diferentes proyectos. El objetivo es
hacer que la experiencia disponible para otros equipos de proyecto para estudiar y, si es posible en toda la empresa, a la
reutilizacin. Los documentos estn disponibles a travs de una intranet. Colegas pueden buscar esta intranet para documentos
que son relevantes para una tecnologa en particular oa un dominio de aplicacin particular.

Se aadi la documentacin del diseo de interfaz grfica de usuario a este registro, por lo que los futuros proyectos GUI podran
bene fi ciarse de la experiencia adquirida, especialmente con la ergonoma GUI. La documentacin tambin se us como material
ejemplar en un seminario interno en las especi fi caciones, en el que los ingenieros de software ms experimentados transmiten sus
conocimientos a sus colegas ms jvenes.

Proyecto Vista tambin contribuy a que la base de conocimientos, y, adems, se convirti en el tema para un
artculo en la revista organizacin de software en la empresa, como se describe en el informe del proyecto en la
pgina 186.

Obviamente, no todos los documentos del proyecto son candidatos para una organizacin de
CONOCIMIENTO ADMINISTRACIN. Sin embargo, cuando un equipo mantiene una ENFOQUE EN EL LARGO PLAZO PERTINENCIA
en lo que se refiere a la documentacin, lo ms probable es que algunos documentos pueden ser tiles en
contextos futuros. Documentos que describen el FUNDAMENTOS DE DISEO son particularmente tiles - la
discusin de la
Informes de experiencia 191

ventajas y desventajas de diferentes enfoques es exactamente lo que ser ms til para proyectos futuros.

Proyecto persistor: alimentar la base de conocimientos de la organizacin

La documentacin que se incluye una descripcin de la tcnica de control de versiones especial la capa de acceso de datos utiliza -
versiones de dos dimensiones (Figura 21 en la pgina 89). Esta es una tcnica bastante especializado, pero es bastante comn para
el almacenamiento y recuperacin de informacin en la industria financiera. Una vez que el concepto se haba entendido, estaba claro
que otros proyectos podran bene fi cio de la experiencia tambin.

Un miembro del equipo elabor un documento de introduccin para la base de conocimientos de la organizacin. En este artculo se explica
los conceptos bsicos de control de versiones de dos dimensiones y se utilizan los mismos ejemplos que tenan el concepto de uso de la
estructura. Este documento se podra producir con relativamente poco esfuerzo, ya que la mayora del material fue fcilmente disponible.
Varios colegas utilizaron este documento como fuente de informacin cuando se les asign un proyecto en el que el control de versiones de
dos dimensiones jug un papel.

Por ltimo, el Proyecto Contentis demuestra que GESTIN DEL CONOCIMIENTO no slo sobre la recogida de
informacin, sino tambin de recuperacin y uso de la misma. Este proyecto fue capaz de entregar un
resultado mucho ms rpido debido a que el equipo podra depender de las experiencias de proyectos
anteriores - un buen ejemplo de cmo los documentos de inters puede ser en el largo plazo.

Proyecto Contentis: el conocimiento recogido de los requisitos de CMS

Este proyecto tena un plazo de tiempo ms corto en el que el equipo tuvo que subir con una lista de requisitos para un
sistema de gestin de contenidos web.

El equipo podra bene fi cio del hecho de que su organizacin haba hecho la consulta sobre los sistemas de gestin de
contenidos web antes, y que la experiencia que ya estaba disponible. En pocos das, el equipo tuvo varias listas Ejemplo de
requisito de proyectos anteriores en sus manos. Estas listas no podan utilizarse pie de la letra, por supuesto, ya que los
requisitos tenan que adaptarse a las necesidades especficas del cliente. De hecho - y como era de esperar - lo que se
utiliza la mayor parte del tiempo en el proyecto fue la cifra cules eran los requisitos especficos. Sin embargo, las listas de
los requisitos de los proyectos anteriores fueron tiles, ya que el equipo no tiene que empezar de cero, pero podra basarse
en material existente. Alternativamente, una vez finalizado el proyecto, una nueva lista de requisitos podra aadirse a la
base de conocimientos de la organizacin.
Observaciones finales

Ahora que ha llegado hasta aqu, cules son los siguientes pasos? Ha ledo los patrones en la
documentacin gil, o al menos algunos de ellos, y probablemente ha echado un vistazo a los informes
de la experiencia de los proyectos en los que se utilizaron los patrones. La pregunta ahora es, qu se
puede hacer para mejorar realmente los procesos de documentacin y los productos de documentacin
en su proyecto? En su libro sobre Desarrollo gil de Software, Alistair Cockburn recomienda: 'Considerar
gil como una actitud, no una frmula'. Y contina: 'En ese estado de nimo, mira a su proyecto actual y
preguntar, Cmo podemos, en esta situacin, el trabajo de una manera gil?' (Cockburn 2001).

Creo que este enfoque es tan viable para la documentacin gil como lo es para el desarrollo gil
de software, y le recomiendo que tome este enfoque cuando se va a solicitar la documentacin
giles en su proyecto. Despus de que se ha familiarizado con las ideas generales de la
documentacin gil, se puede ver en su proyecto y ver cmo la documentacin se puede hacer con
un gil actitud.

En este punto, me gustara recordar los principios de la documentacin gil.

embargo, que proporciona


documentacin del proyecto toda
es la informacin
ms eficaz relevante
cuando parasin
es ligero, losningn
lectores.
tipo de documentos innecesarios,
escriben
que bien,
deben ser pero tratan de
abordados en hacerlo
documentossin ms documentacin.
escritos. Asegrese Centrarse
de que en los
estos materialesestn
documentos adecuados. Lay sin
escritos, se
cortas. Un proyecto gil da preferencia a la documentacin
Ms documentacin no es siempre mejor que menos. Los documentos de peso ligero.
largosBuscar lossiempre
no son temas en los que
mejores quesiente
las
194 Observaciones finales

Los documentos que se consideren necesarios slo pueden resultar tiles si son de alta calidad:
informacin precisa y actualizada, de fcil lectura y legible, concisa y bien estructurada.

Una vez que haya decidido que un documento es necesario, no producen ese documento a
medias. El documento puede servir a su propsito bien slo si es preciso y bien organizado. La
rectitud har sus documentos bien.

Herramientas y tcnicas son tiles slo si facilitan la produccin de documentos de alta calidad
y hacer que su organizacin y mantenimiento ms fcil.

Adoptar un enfoque imparcial para herramientas. Las herramientas se supone que le ayudar en su trabajo, y la
documentacin no es una excepcin. Si las herramientas hacen que la documentacin en su proyecto ms difcil,
prescindir de ellos. Tenga en cuenta que las tcnicas relativamente simples a menudo son su fi ciente para producir
documentacin til.

El proceso de documentacin debe ser e fi ciente y directo, debe adaptarse a los requisitos del
proyecto individual y debe ser capaz de responder al cambio.

No definen un proceso complejo para la documentacin. Alistair Cockburn escribe: ' gil implica ser eficaz y
fcil de manejar. Un gil proceso es a la vez ligero y su fi ciente'(Cockburn 2001). Acaba de tomar las
medidas que sean necesarias: asegrese de que una buena documentacin est escrito, por las personas
adecuadas, y con un esfuerzo razonable, pero no hacer planes ms all de ese punto. Cmo puede
empezar?

Empieza pequeo. El comenzar pequeo es mucho ms prometedora de tratar de lograr todo a la


vez, como Mary Lynn Manns y Linda Rising punto de salir cuando recomiendan la introduccin de
nuevas ideas Paso a paso ( Manns Rising
2003).

Comience con unos patrones de este libro que usted siente que puede aplicar en su proyecto fcilmente. Los
patrones sobre la estructuracin de documentos individuales, por ejemplo, a menudo pueden ser aplicadas
inmediatamente. Otras cosas, tales como el establecimiento de procesos, pueden tardar un poco ms, pero no
requieren un esfuerzo demasiado grande tampoco.
Observaciones finales 195

Integrar estos patrones en su trabajo diario en forma incremental. Si tiene identi fi c un patrn que
le gustara usar, los enlaces a los patrones relacionados dir qu otros temas es posible que desee
considerar. De esta manera se puede construir una cultura de la documentacin gil, una actitud
de la preparacin de documentos de tal manera que sean tiles para los dems, sus clientes y sus
colegas por igual.

La aplicacin de las pautas para la documentacin gil es gratificante en el sentido de que sus
lectores apreciarn y pro fi ciarse de su trabajo ms. documentacin gil le anima a prescindir de
algunos de los trmites que se encuentra en proyectos de ms peso, pero se asegura de que el
esfuerzo que haces lugar en sus documentos as vale la pena. Se le ampliamente recompensado por
la e fi ciencia de la comunicacin en su proyecto.
patrn de miniaturas

Encontrar los temas correctos


Los lectores de destino Cmo puede el equipo del proyecto asegurarse de que los documentos que producen sern

apreciado?

En primer lugar, cada documento debe tener un pblico objetivo, y debe hacer frente a estos
lectores con el fin de ser til.

La informacin Cmo se pueden prevenir los documentos de meandros y llegar a ninguna parte?
centrada
A fi cables enfoque claro e identi sobre un tema en particular hace un documento conciso y directo.
El documento sencillo ofrece la informacin relevante a este tema, pero no ms que eso.

Individual Cmo se pueden evitar los requisitos de documentacin innecesarios?


Requisitos de
El enfoque ms eficaz para la documentacin es para cada proyecto para definir sus requisitos de
documentacin
documentacin de forma individual.

Cartera Cmo pueden los equipos de reutilizar el conocimiento sobre la cual podran ser necesarios documentos en sus
documentacin proyectos?

Una cartera documentacin describe los documentos que podran ser necesarios en un proyecto de
software, y su alcance. Si una organizacin establece dicha cartera, los proyectos pueden elegir aquellos
documentos que necesitan, comprobando la necesidad de cada documento individual candidato.
198 patrn de miniaturas

Centrarse en la Cmo pueden evitar la produccin de proyectos de documentacin que expira antes de tiempo?
pertinencia LongTerm
Hay mucho valor en la documentacin que se centra en los problemas a largo plazo con una relevancia - cuestiones
que desempearn un papel en una fase posterior del proyecto o en proyectos futuros.

Espec fi cacin como un Cmo pueden los proyectos de desarrollo de asegurar que se dirigen en la direccin que el cliente quiere?
esfuerzo conjunto

Cada proyecto de desarrollo requiere una especificacin, que re fl eje el anlisis de necesidades
realizado conjuntamente por el equipo del proyecto y el cliente.

Fundamentos Cmo puede el equipo asegurarse de que se sientan las bases para futuros cambios de diseo?
de diseo

Los documentos de diseo se convierten en una valiosa fuente de informacin, si no se limitan a


describir el diseo actual, pero tambin se centran en la razn de ser del diseo y explican por qu
se eligi el diseo particular.

El panorama Cmo se pueden introducir a la gente a un proyecto sin ser confrontado con una
diluvio de informacin tcnica?

Una buena idea de un proyecto es mejor transmite a travs de una descripcin de la 'gran imagen' de la
arquitectura que subyace en el sistema en construccin.

La separacin de Cmo pueden los autores evitar la prdida de credibilidad?


descripcin y
Autores ganan credibilidad si, en sus documentos, que la descripcin claramente separada de la
evaluacin
evaluacin.

Los ejemplos Cmo puede explicarse abstracto material de una manera comprensible?
realistas
Los documentos del proyecto son mucho ms convincente si incluyen ejemplos reales de contexto
del proyecto.

La estructuracin de los documentos individuales


La informacin Cmo puede la informacin sea presentada de una manera fcilmente accesible?
estructurada
La mayora de los documentos del proyecto estn mejor organizados como texto secuencial sin embargo, bien estructurado. Esto

comienza con los captulos y secciones bien elegidos, pero tambin puede extenderse a la utilizacin de bloques de construccin

textual coherente en todo el documento.


La estructuracin de los documentos individuales 199

Diagramas Cmo pueden los autores proporcionar una visin general de las estructuras y procesos de una manera conveniente?
juiciosas

Los diagramas pueden proporcionar excelentes vistas generales, mientras que un texto que la acompaa explica los detalles
en la medida en que sea necesario.

Tablas sin Cmo pueden autores presentan informacin sistemtica de una manera precisa?
ambigedades
Mesas ofrecen un formato compacto para la presentacin concisa e inequvoca de la informacin.

Directrices para los Cmo se puede informar a los lectores potenciales si deben leer un documento, y si es as, en qu
lectores partes deben concentrarse?

Algunas directrices breve al comienzo de cada documento pueden informar a los lectores potenciales
de la finalidad del documento sirve y explicar cmo los diferentes grupos de lectores deben acercarse
al documento.

Thumbnail Cmo pueden los lectores obtener una visin general de los temas tratados en un documento?
Sketches
bocetos en miniatura proporcionan breves descripciones de las secciones de un documento, incluidos los objetivos
generales de la seccin, as como sus principales ideas.

Referencias Cmo pueden ser documentos vinculados el uno al otro?


trazables
Un documento debe incluir referencias a otros documentos slo si los lectores pueden obtener esos
documentos sin mucho esfuerzo.

Glosario Cmo pueden autores asegurarse de que los lectores a comprender el vocabulario utilizado en un documento?

Un glosario puede explicar trminos tcnicos, as como los trminos espec fi cos para el dominio de aplicacin.

Historia del Cmo se puede evitar la confusin entre las versiones de un documento?
documento
Un historial de documentos puede explicar las diferencias en las versiones anteriores de un documento,
y puede relacionar el documento a versiones del software que describe.
200 patrn de miniaturas

Diseo y la tipografa
Texto en el 50% de una Cunto espacio en una pgina debe ser dedicado al texto?
pgina
Alrededor del 50% de la pgina debe ser dedicado a texto.

Dos alfabetos por Cul es el ancho de la lnea ptima?


lnea
Aproximadamente dos alfabetos minsculas del tipo de letra estndar deben encajar en una lnea.

120% Cul es el espaciado de lnea ptima?


Interlineado
La mejor separacin de lneas es aproximadamente 120% del tamao de letra.

dos Tipos de letra Cuntos tipos de letra son apropiadas y que?

En la mayora de los casos, dos tipos de letra por documento son apropiados - un tipo de letra serif para el texto
principal y una tipografa sans serif para los ttulos.

El uso cuidadoso de las Cmo se pueden destacar partes de un texto?


modificaciones de tipo
variaciones de tipo pueden ser utilizados para dar nfasis, pero deben usarse con cuidado.

Sentencia cuidado y Cmo se pueden separar celdas de la tabla?


sombreado
Cuidado gobernante y el sombreado conduce a tablas altamente legibles.

La colocacin Cmo pueden las tablas y diagramas pueden integrar en el texto?


adyacente
Diagramas y tablas estn mejor cerca del texto de la que se hace referencia.

Pginas coherentes Qu opciones existen para evitar la paginacin incmoda que desgarra informa- relacionados

Tion aparte?

La lectura de flujo se apoya en las pginas coherentes - pginas que asegurarse de que aparezca un mnimo
de informacin relacionada a cada lado de un salto de pgina.
Infraestructura y Organizacin Tcnica 201

Infraestructura y Organizacin Tcnica


Paisaje Cmo pueden los miembros del equipo tengan una buena visin general de lo que existe en la documentacin de un proyecto?
documento

La documentacin del proyecto se puede representar como una especie de paisaje que los miembros del equipo
pueden utilizar como un mapa mental cuando se recuperan o aadir informacin. Un paisaje documento que ms o
menos se forma un rbol se adapte mejor intuicin humana.

Archivo de Cmo pueden los proyectos de evitar la prdida de cualquiera de las versiones de documentos?
documentos
documentacin de proyecto de archivo ofrece la ventaja de que las versiones se pueden recuperar cuando sea
necesario.

wiki Cmo puede la documentacin se dar una ventaja ms interactivo?

Un Wiki ofrece acceso a la documentacin del proyecto a travs de un servidor de intranet, y, adems,
permite al equipo para publicar notas y mensajes a otros segn sea necesario.

Cdigo-comentario de Cul es una manera fcil de mantener la documentacin que hace referencia al cdigo real?
proximidad

Documentacin del cdigo, en la medida en que un equipo de proyecto considera necesario, es mejor
hacerlo a travs de comentarios de cdigo fuente. documentos separados deben reservarse para problemas
de nivel superior, tales como resmenes, requisitos, diseo y arquitectura.

De fcil Qu es ms apropiado: los documentos destinados a ser utilizados en lnea o documentos destinados a la impresin?
lectura-Medios

La eleccin de un medio debe reflejar el uso tpico de un documento. La regla de oro es: impresin es
buena para la lectura, en lnea es bueno para mirar las cosas.

Separacin de Cmo pueden los diseos de documentos de texto pueden modificar y volver a utilizar fcilmente?
Contenido y
estilos de diseo pueden ser de fi nido y se asigna a porciones de contenido. Estos estilos de diseo se pueden cambiar
disposicin
fcilmente y se pueden reutilizar a travs de los documentos.
202 patrn de miniaturas

Fuente nica y Cmo pueden los mltiples puntos de vista de un documento pueden crear sin duplicar el mantenimiento?
Objetivos
Mltiples
La infraestructura de la documentacin puede emplear mecanismos que tienen documentos de origen y
generan automticamente vistas adicionales. Tales mecanismos evitar la doble mantenimiento y
garantizar la coherencia.

Importacin por Cmo pueden los diferentes documentos utilizar el mismo diagrama o tabla consistente?
referencia
Artefactos que deben aparecer en mltiples contextos pueden ser importados por referencia en los
documentos que los incluyen.

La separacin de Cmo pueden producir proyectos de documentos tiles, imprimibles?


procesamiento e
Si un equipo elige para entregar la documentacin del proyecto en un formato de impresin que est ampliamente disponible,
impresin
todos los lectores son capaces de imprimir los documentos, independientemente de la plataforma que utilizan.

plantillas de Cmo pueden todos los documentos del proyecto adquirir una estructura razonable y un buen diseo a bajo costo?
documentos

plantillas de documentos, una vez que han sido diseados adecuadamente, imponen su estructura y el
diseo de todos los documentos que se producen de usarlos.

pocas herramientas Cmo pueden los proyectos minimizar el esfuerzo dedicado a la introduccin y el uso de herramientas de
documentacin?

Casi todos los proyectos pueden manejar con un pequeo conjunto de herramientas de documentacin.

Los cambios Cmo pueden los autores evitar la confusin sobre los cambios que han hecho?
anotado
Mientras que un documento se encuentra en desarrollo, los autores pueden utilizar las anotaciones automticas para
identificar aquellas partes del documento que han cambiado recientemente.

Notificacin sobre la Cmo se pueden prevenir los lectores del uso de versiones no actualizadas?
actualizacin
Cada vez que hay un cambio significativo en un documento de proyecto, todos los lectores potenciales
deben ser noti fi cado de la nueva versin. La noti fi cacin debe explicar ms o menos lo que se ha
cambiado, pero no debe incluir el material actualizado en s.
Gestin y Aseguramiento de la Calidad 203

Reorganizacin a Cmo se puede mantener la infraestructura de la documentacin?


peticin
reorganizacin frecuente empeora las cosas, no mejor. Reorganizacin de la infraestructura de la
documentacin debe tener lugar slo cuando es solicitado activamente por los miembros del equipo
del proyecto.

Gestin y Aseguramiento de la Calidad


Una actividad Cmo se deben asignar recursos a las actividades de documentacin?
distinta
Cuando la documentacin se considera una actividad de proyecto distinto, y no slo el subproducto de
codificacin, se le puede asignar su propio presupuesto, la prioridad y el horario. Documentacin entonces
se puede pesar en contra de otras actividades pr oyecto.

Uno Cuntas personas deben ser responsables de un documento?


responsable
Para cada documento del proyecto, tiene que haber una persona que acepta la responsabilidad por ello.
Autor
Esta persona no tiene que escribir el documento solo, pero debe coordinar las contribuciones de otras
personas.

Documentacin Cuando se debe escribir la documentacin del proyecto?


continua
La documentacin del proyecto, cuando se evoluciona continuamente a medida que el proyecto avanza, ofrece la
ventaja de que re fl eja el ltimo estado estable del proyecto.

La escritura y la Cmo pueden documentacin y otras actividades del proyecto estimular el uno al otro?
reflexin
Para sacar el mximo partido de la documentacin, los miembros del equipo tienen que pasar tiempo en la
escritura real, as como en la reflexin sobre lo que han escrito, preferiblemente en un entorno tranquilo.

revisin Cultura Cmo se puede mejorar la calidad de los documentos del proyecto?

La documentacin puede bene fi cio muchos de los comentarios, siempre una cultura opinin se ha establecido en
la cual ambos autores y los colaboradores se sientan cmodos.

Revisin Antes de Cmo pueden los autores recibir la retroalimentacin adecuada en el momento adecuado?
entrega
Las primeras crticas son definir, ya que ayudan al autor a determinar el alcance y la estructura de un
documento. Pero antes de que un documento es de fi cialmente distribuye o entrega al cliente, una
revisin es obligatoria.
204 patrn de miniaturas

Crtica de Cmo puede utilizar un equipo de documentacin para aumentar la implicacin del cliente?
consumidor
Comentarios de los lectores pueden mejorar la calidad de un documento, especialmente en lo que se refiere a la
experiencia en el campo, y al mismo tiempo aadir a la formacin de equipos y la integracin.

Una vista distante Cmo pueden los autores obtengan retroalimentacin imparcial?

Los autores pueden obtener retroalimentacin imparcial de los colaboradores que estn interesados en el tema y
que por lo general tienen conocimiento en el campo, pero que no estn involucrados en el trabajo real se
describe en el documento.

informacin del Cmo se pueden prevenir buenos documentos de ir tristemente inadvertido?


mercado
Documentos ganan ms atencin si los presuntos lectores estn invitados activamente para leerlos.

Gestin del Cmo pueden los proyectos futuros bene fi cio de un proyecto exitoso?
conocimiento
Slo cuando la documentacin del proyecto se pone a disposicin de toda la organizacin hacer proyectos de futuro
tienen la oportunidad de aprovechar la experiencia adquirida.
Glosario

Agile Alliance
Un grupo de 17 personas que primero se reuni en febrero de 2001 con el objetivo de hallazgo mejores
formas de desarrollo de software. los autores del Manifiesto gil.

Ver www.AgileAlliance.org.

Desarrollo gil
El desarrollo de software siguiendo los principios expresados en la Manifiesto gil.

Manifiesto gil
Una coleccin de valores y principios fundamentales destinados a conducir a mejores formas de desarrollo de
software, tal como se define por la Agile Alliance.

Ver www.AgileManifesto.org.

proceso gil
Cualquier proceso - la especificacin, modelado, diseo, la codificacin u otro proceso - que sigue los
principios expresados en la Manifiesto gil.

Autor
Para los propsitos de este libro, cualquier persona que escribe un proyecto documento. Por lo general se trata
de un miembro del equipo que tambin tiene otras tareas. Casi nunca un escritor tcnico profesional.

CASO

la ingeniera de software asistida por computadora, como en 'herramienta CASE'.


206 Glosario

Diagrama de clase

UN UML diagrama que muestra las clases, sus atributos y sus operaciones, as como diversas
relaciones estticas que existen entre estas clases, tales como asociacin, la agregacin y la
herencia.

Contenido

El texto real de una documento, independiente de diseo o formato.

libro de cocina

UN documento que se explica cmo utilizar un sistema de software a travs del asesoramiento paso a paso.

entregable
Cualquier artefacto que un proyecto se supone que debe entregar al cliente. Esto puede incluir el cdigo
fuente, software ejecutable y documentos.

documento de diseo

UN documento que describe cmo el software est organizado internamente y por qu est organizado de esa
manera. Por lo general, un documento de diseo describe cmo el software se compone de partes ms
pequeas y cmo se relacionan estas partes. Los diagramas de clases y diagramas de interaccin son a menudo
el mtodo de eleccin para describir un diseo.

Documento
Un artefacto persistente que est configurado especficamente para proporcionar informacin por escrito. Un
documento se produce tpicamente por va electrnica, y se puede leer ya sea como una copia impresa o en lnea.

Documentacin
La totalidad de documentos y comentarios de cdigo fuente producen en un proyecto. Tambin el
proceso que comprende la coleccin, clasificacion y la difusin de informacin.

Procesamiento de documentos

El proceso de crear, editar, cambiar, mantener e impresin documentos, como se hace tpicamente
con una procesador de textos.

Fuente

El conjunto de caracteres que pertenecen a un cierto tipo de letra de un tamao dado.


Glosario 207

HTML
Hipertexto lenguaje de marcas. Un lenguaje utilizado para definir la apariencia y el comportamiento de las
pginas cuando se muestra en un navegador Web. HTML permite la definicin de bloques de texto, as como la
de fi nicin de hipervnculos.

hipertexto
Texto organizada de una manera no secuencial con hipervnculos proporcionar acceso de un trozo de
informacin a otros. Tpicamente, varias rutas de acceso permiten lectores viajar a travs de un
hipertexto de diferentes maneras.

diagrama de interaccin

UN UML diagrama que visualiza el paso de mensajes entre los objetos colaboradoras.

Diseo
El conjunto de caractersticas que definen una documentos apariencia visual.

Legibilidad

El grado en que una pgina impresa se puede reconocer de forma rpida y fiable. La legibilidad depende
principalmente de lo bien lectores puede identificar los caracteres de la tipo de letra usado.

Meta informacion
En el contexto de documentacin, un trozo de texto o un grupo de palabras clave que proporcionan
informacin sobre el documentos el estado y el tipo de informacin que contiene.

On-line documento
UN documento que est destinado a ser ledo con el uso de un navegador web u otra aplicacin de
visualizacin. A menudo acceder al documento se da a travs de Internet o de una intranet en la casa, pero el
documento tambin pueden estar situados en el equipo local. documentos en lnea pueden tener
hipervnculos por el cual los documentos pueden ser vinculados.

formato de prrafo
Una especificacin que define las propiedades de formato para todos los prrafos de un tipo dado dentro de una documento,
tal como se utiliza en una procesador de textos.
208 Glosario

PDF
Formato de Documento Porttil - un sistema electrnico documento formato desarrollado por Adobe Systems Inc., que
es portable entre diferentes tipos de equipos, diseados para su visualizacin en lnea, pero ahora tambin se utiliza
como una formato de impresin.

Posdata
UN documento Descripcin lenguaje diseado para ser una formato de impresin portable entre los dispositivos de
impresin.

Imprimir documento

UN documento destinado a la impresin, en contraposicin a una documento en lnea.

formato de impresin

Una especificacin que describe exactamente cmo una documento aparecer cuando se imprima.
Ejemplos incluyen PDF y Posdata.

Legibilidad
El grado en que un texto puede ser fcilmente agarrado y entendido por el
lector.

Lector
Una persona que utiliza una documento para obtener la informacin en un nivel arbitrario de detalle. Esto
incluye no slo los que leen un documento de principio a fin, sino tambin a los lectores ocasionales que
navegar a travs de un documento en bsqueda de informacin especfica.

refactoring
Reorganizacin de un sistema de software sin cambiar su comportamiento externo, con el objetivo de
mejorar su estructura interna. Cuando se aplica a la documentacin: la mejora de la estructura de la
documentacin del proyecto sin modificar su contenido.

revisin
El proceso de tener una documento revisado por una persona distinta del
autor, tpicamente con la intencin de mejorar la calidad del documento con respecto a la contenido, estructura
y el lenguaje.

proyecto de software

Un proyecto cuyo objetivo es de alguna manera relacionada con el desarrollo de software. Esto puede ser un
proyecto de desarrollo en el que la entregables son elementos de
Glosario 209

software, o puede ser un proyecto de consultora que todava tiene que ver con el desarrollo de software,
aunque de una manera menos directa.

documento especi fi cacin

UN documento que describe lo que se supone que un producto de software que hacer. Una especi fi cacin de
documentos de fi ne los requisitos que debe cumplir el software.

Modelo
Un artefacto que no es en s misma una documento, pero espec fi ca del diseo y el formato de una clase de
documentos similares. Ms procesadores de palabras apoyar el uso de plantillas de documentos.

Miniatura
Un breve resumen de un texto ms largo.

Tutorial
UN documento que se explica cmo utilizar un sistema de software.

Tipo de letra

Una coleccin de caracteres, incluyendo letras, nmeros y smbolos, destinada a la presentacin visual de la
lengua y todos ellos diseados en un estilo similar. Los ejemplos incluyen Times, Helvetica, Garamond y
Frutiger. La mayora de los tipos de letra estn diseados como familias e incluyen conjuntos de caracteres
para diferentes tamaos, as como las variaciones tales como negrita, cursiva y casquillos pequeos.

tamao de letra

El tamao de una tipo de letra, normalmente medido en puntos. Un rango tpico de tipo tamaos adecuados para
impresa documentos es de 8-24 puntos.

Tipografa
La ciencia, del arte o el arte de la creacin de una pgina impresa. ofertas de tipografa con letras, diagramas,
lneas, superficie y color.

UML
Unificado de Modelado del lenguaje.

ARRIBA

Uni Proceso fi ed.


210 Glosario

caso de uso

Una secuencia de acciones a llevar a cabo con un sistema de software que, en su conjunto, representan un
escenario de uso tpico.

Procesador de textos

Para los propsitos de este libro, una herramienta para Procesamiento de documentos. Los procesadores de texto
cubren diferentes grados de complejidad, que van desde simples editores de texto a los sistemas de autoedicin
sofisticados.
referencias

Alexander Ishikawa Silverstein 1977


Christopher Alexander, Sara Ishikawa, Murray Silverstein: Un Lenguaje de Patrones -
Poblaciones Edificios Construccin, Oxford University Press, Nueva York, 1977. Alexander
1979

Christopher Alexander: La manera atemporal de construccin, Oxford University Press, Nueva


York, 1979. Ambler 2002

Scott W. Ambler: Prcticas efectivas para eXtreme Programming y la fi Proceso unificado, -


Modelado gil John Wiley & Sons, 2002. Beck Cunningham 1989

Kent Beck, Ward Cunningham: 'un laboratorio para la enseanza orientada a objetos
Pensamiento ', en Actas de OOPSLA '89, ACM Press, 1989. Beck 2000

Kent Beck: Extreme Programming Explained: aceptar el cambio,


Addison-Wesley, 2000.
Berczuk Appelton 2003
Steve Berczuk, Brad Appelton: Software de Con fi guracin patrones de manejo: el trabajo
en equipo, la integracin prctica, Addison-Wesley,
2003.

Berleant 2000
Daniel Berleant: 'Tiene la tipografa afecta la evaluacin de propuestas', en
Communications of the ACM, Vol. 43, No. 8, agosto de 2000.
212 referencias

Botafogo Rivlin Shneiderman 1992


Rodrigo A. Botafogo, Ehud Rivlin, Ben Shneiderman: 'Anlisis Estructural de hipertextos:
Jerarquas identificar y mtricas tiles', En ACM Transactions on Information Systems, Vol. 10,
No. 2, abril de 1992. Marca 1999

Stewart Brand: El reloj de la Long Now - El tiempo y la Responsabilidad,


Libros bsica, Nueva York, 1999. Brooks

1995

Frederick P. Brooks: El mes laboral mtico, Addison-Wesley, Anniversary Edition, 1995.

Buschmann Meunier Rohnert Sommerlad Stal 1996


Frank Buschmann, Regine Meunier, Hans Rohnert, Peter Sommerlad, Michael Stal: Patrn-Oriented
Software Architecture - un sistema de modelos, John Wiley & Sons, 1996. Cockburn 1998

Alistair Cockburn: Sobrevivir a proyectos orientados a objetos - Gua del Gerente, Addison-Wesley,
1998. Cockburn 2000

Alistair Cockburn: Escribiendo uso efectivo casos, Addison-Wesley, 2000. Cockburn 2001

Alistair Cockburn: Desarrollo gil de Software, Addison-Wesley, 2001. Conover 1985

Theodore E. Conover: Comunicaciones Grficas Hoy en da, West Publishing Company,


1985. Coplien 1995

James O. Coplien: 'Un modelo generativo-Proceso de Desarrollo


Lenguaje', en Lenguajes de Patrones de diseo del programa, Vol. 1, James O. Coplien,
Douglas C. Schmidt (Eds.), Addison-Wesley, 1995. Coplien 2000

James O. Coplien: "Una lengua del patrn de los escritores Talleres, en


Lenguajes de Patrones de diseo del programa, Vol. 4, Neil Harrison, Brian Foote, Hans
Rohnert (Eds.), Addison-Wesley, 2000.
referencias 213

Crowder 1982
Robert G. Crowder: La psicologa de la lectura, Prensa de la Universidad de Oxford,
mil novecientos ochenta y dos.

DeMarco Lister 1987


Tom DeMarco, Timothy Lister: Peopleware: Proyectos Productivos y equipos, Dorset
House, 1987. (2 edicin, Dorset House, 1999.) Dumais 1988

Susan T. Dumais: 'Pruebas de recuperacin de informacin,' en Manual de Interaccin


Hombre-Mquina, Elsevier (norte de Holanda), 1988. EuroPLoP 1998

Jens Coldewey, Paul Dyson (Eds.): Actas de la 3 Conferencia Europea sobre Lenguajes de
Patrones de los programas, 1998, Universittsverlag Konstanz. EuroPLoP 1999

Paul Dyson, Martine Devos (Eds.): Actas de la 4 Conferencia Europea sobre Lenguajes de
Patrones de los programas, 1999, Universittsverlag Konstanz. EuroPLoP 2000

Martine Devos, Andreas Rping (Eds.): Actas de la 5 Conferencia Europea sobre Lenguajes
de Patrones de los programas, 2000, Universittsverlag Konstanz. EuroPLoP 2001

Andreas Rping, Jutta Eckstein, Christa Schwanninger (Eds.):


Actas de la 6 Conferencia Europea sobre Lenguajes de Patrones de los programas, 2001, Universittsverlag
Konstanz. Flanagan 2002

David Flanagan: Java en una cscara de nuez, O'Reilly & Associates, 2002. Fowler 1996

Martin Fowler: Los patrones de anlisis, Addison-Wesley, 1996. Fowler 2000

Martin Fowler: UML destilada, 2 edicin, Addison-Wesley, 2000.


214 referencias

Furnas Zacks 1994


George W. Furnas, Jeff Zacks: 'Multitrees: Riqueza y la reutilizacin de la estructura jerrquica, en' CHI
'94 - Actas de la Conferencia sobre Factores Humanos en Sistemas Informticos, ACM, 1994. Gabriel
2002

Richard Gabriel: Talleres de escritura, el trabajo de hacer las cosas: Patrones, Poesa ... Addison-Wesley,
2002. Gamma timn Johnson Vlissides 1995

Erich Gamma, Richard Helm, Ralph Johnson, John Vlissides: Patrones de diseo: Elementos
de software reutilizables orientada a objetos, Addison-Wesley, 1995. Glasser 1992

Theodore L. Glasser: 'La objetividad y noticias Sesgo,' en Cuestiones filosficas en el


periodismo, Elliot D. Cohen (Ed.), Oxford University Press, 1992. Gulbins Kahrmann 1992

Jrgen Gulbins, Christine Kahrmann: Mut zur Typographie, Saltador,


1992. (en alemn)
Haramundanis 1998
Katherine Haramundanis, El arte de la documentacin tcnica, Butterworth-Heinemann,
1998. Harrison 1996

Neil B. Harrison: "Los patrones de organizacin de equipos, en Patrn


Idiomas del diseo del programa, Vol. 2, John M. Vlissides, James O. Coplien, Norman L.
Kerth (Eds.), Addison-Wesley, 1996. Harrison 2000

Neil B. Harrison: 'La lengua del patrn de pastoreo', en Lenguajes de Patrones de diseo
del programa, Vol. 4, Neil Harrison, Brian Foote, Hans Rohnert (Eds.), Addison-Wesley, 2000.
Highsmith 2000

Jim Highsmith: Adaptativa de desarrollo de software, Dorset House, 2000. Highsmith 2002

Jim Highsmith: Agile Software ecosistemas de desarrollo, Addison-Wesley,


2002.
referencias 215

cuerno de 1989

Robert E. Horn: Mapeo de hipertexto, Lexington Institute, 1989. Horton 1994

William Horton: El diseo y la documentacin en lnea de escritura, John Wiley & Sons, 2
edicin, 1994. Hsu Mitchell 1997

Richard C. Hsu, William E. Mitchell: 'Despus de 400 aos, de impresin sigue siendo superior', en Communications
of the ACM, Vol. 40, No. 10, octubre de 1997. Jacobsen Booch Rumbaugh 1999

Ivar Jacobsen, Grady Booch, James Rumbaugh: La fi cada proceso de desarrollo de software
Uni, Addison-Wesley, 1999. Kerth 2001

Norman Kerth: Retrospectivas del proyecto: Un manual para las revisiones del equipo,
Dorset House, 2001.
Knuth 1992
Donald E. Knuth: Programacin leer y escribir, Centro para el Estudio de la Lengua y de la
Informacin, 1992. Kruchten 2000

Philippe Kruchten: El Rational Uni fi Proceso ed, Addison-Wesley, 2000. Leuf Cunningham
2001
Bo Leuf, Ward Cunningham: El Wiki Way, Addison-Wesley, 2001. El aumento de Manns

2003

Mary Lynn Manns, Linda Rising: El miedo menos y otros patrones para la introduccin de nuevas
ideas en las Organizaciones, 2003 (en preparacin). Miller 1956

George A. Miller: 'El nmero mgico siete, ms o menos dos: algunos lmites en nuestra
capacidad de procesamiento de informacin', en Psychological Review, Vol. 63, N 2, American
Psychological Association, marzo de 1956. Nielsen 2000

Jakob Nielsen: El diseo de Usabilidad Web - La prctica de la simplicidad, New Riders Publishing,
2000.
216 referencias

Noble Weir 2000


James Noble, Charles Weir: Software pequea de memoria, Addison-Wesley,
2000.

Orenstein 1996
Robert Orenstein: 'Una lengua del patrn para un sitio Web de Ensayo-base', en
Lenguajes de Patrones de diseo del programa, Vol. 2, John M. Vlissides, James
O. Coplien, Norman L. Kerth (Eds.), Addison-Wesley, 1996.
Pinker 1997
Steven Pinker: Cmo funciona la mente, Allen Lane, The Penguin Press,
1997.

PLoPD 1995

James O. Coplien, Douglas C. Schmidt (Eds.): Lenguajes de Patrones de diseo del programa, Vol.
1, Addison-Wesley, 1995. PLoPD 1996

John M. Vlissides, James O. Coplien, Norman L. Kerth (Eds.): Lenguajes de Patrones de diseo
del programa, Vol. 2, Addison-Wesley, 1996. PLoPD 1998

Robert C. Martin, Dirk Riehle, Frank Buschmann (Eds.): Lenguajes de Patrones de diseo
del programa, Vol. 3, Addison-Wesley, 1998. PLoPD 2000

Neil Harrison, Brian Foote, Hans Rohnert (Eds.): Lenguajes de Patrones de diseo del programa, Vol.
4, Addison-Wesley, 2000. Parnas 1972

David Parnas: 'En los criterios que se utilizarn en Sistemas descomponindose en los mdulos',
en Communications of the ACM, Vol. 15, No. 2, Diciembre
1972.

Poppendieck 2003
Mary Poppendieck: Desarrollo magra - Un material gil para los gerentes de desarrollo de
software, 2003 (en preparacin). prensa 2000

Larry Press: 'A partir de P-libros a los libros electrnicos', en Communications of the ACM,
Vol. 43, n 5, mayo de 2000.
referencias 217

2000a Rising
Linda Rising: 'los patrones de interaccin del cliente', en Lenguajes de Patrones de Diseo del
Programa, V ol. 4, Neil Harrison, Brian Foote, Hans Rohnert (Eds.), Addison-Wesley, 2000. El aumento
2000b

Linda Rising: Los patrones de almanaque de 2000, Addison-Wesley, 2000. Rumbaugh

Jacobsen Booch 1998

James Rumbaugh, Ivar Jacobsen, Grady Booch: El Uni fi ed Manual de Referencia del Lenguaje
de Modelado, Addison-Wesley, 1998. Rping 1998a

Andreas Rping: 'La estructura y disposicin de los Documentos Tcnicos', en


Actas de la 3 Conferencia Europea sobre Lenguajes de Patrones de Programacin y
Computacin 1998, Jens Coldewey, Paul Dyson (Eds.), Universittsverlag Konstanz. Rping
1998b

Andreas Rping: 'La escritura y la revisin de los Documentos Tcnicos', en


Actas de la 3 Conferencia Europea sobre Lenguajes de Patrones de Programacin y
Computacin 1998, Jens Coldewey, Paul Dyson (Eds.), Universittsverlag Konstanz. 1999a
Ruping

Andreas Rping: 'Gestin de Documentacin del proyecto', en Actas de la 4 Conferencia


Europea sobre Lenguajes de Patrones de Programacin y Computacin 1999, Paul Dyson,
Martine Devos (Eds.), Universittsverlag Konstanz. Rping 1999b

Andreas Rping: 'La tipografa y la autoedicin', en Actas de la 4 Conferencia Europea


sobre Lenguajes de Patrones de Programacin y Computacin 1999, Paul Dyson, Martine
Devos (Eds.), Universittsverlag Konstanz. Salton 1989

Gerard Salton: Procesamiento automtico de texto - La transformacin, anlisis y


recuperacin de informacin por ordenador, Addison-Wesley,
1989.
218 referencias

Schmidt Stal Rohnert Buschmann 2000


Douglas Schmidt, Michael Stal, Hans Rohnert, Frank Buschmann:
Patrn-Oriented Software Architecture 2 - Patrones para concurrentes y en red, objetos, John
Wiley & Sons, 2000. Schneider 1996

Wolf Schneider: Deutsch fr Kenner - Die neue Stilkunde, Piper, 1996. (en alemn)
Schneider 1999

Wolf Schneider: Deutsch fr Pro fi s - Wege zu gutem Stil, Goldmann,


1999. (en alemn)
Schwaber Beedle 2001
Ken Schwaber, Mike Beedle: Desarrollo de software gil con Scrum,
Prentice Hall, 2001.
Siedersleben 2003
Johannes Siedersleben (Eds.): Softwaretechnik, Hanser, 2003. (en alemn) Sommerville
1996

Ian Sommerville: Ingeniera de software, Addison-Wesley, 1996. Strunk Blanca


1979
William Strunk, EB White: Los elementos del estilo, Macmillan, 3 edicin, 1979. Tinker
1963

Miles A. Tinker: Legibilidad de impresin, Iowa State University Press, 1963. Tufte 1997

Edward R. Tufte: Explicaciones visuales: Imgenes y cantidades, las pruebas y la narrativa, Grficos
Press, 1997. Tufte 2001

Edward R. Tufte: El Visual Display de informacin cuantitativa,


Grficos Press, 2 edicin, 2001. Vlter
Schmid Wolff 2002
Markus Vlter, Alexander Schmid, Eberhard Wolff: Matrices de componentes del servidor -
Componente Infraestructuras ilustrado con EJB, John Wiley & Sons, 2002.
referencias 219

Weinberg 1998
Gerald M. Weinberg: La psicologa de la programacin informtica, Aniversario de plata
Edicin, Dorset House, 1998. Weir 1997

Charles Weir: 'Patrones de diseo en Equipos: Equipos Cmo puede mejorar el proceso de
diseo', en Lenguajes de Patrones de diseo del programa,
Vol. 3, Robert C. Martin, Dirk Riehle, Frank Buschmann (Eds.), Addison-Wesley, 1997. West
1990

Suzanne West: Trabajar con Estilo: Enfoques tradicionales y modernos para diseo y la
tipografa, Watson Guptill, 1990.
ndice

120% LNEA ESPACIADO 100, 102, 102 - 104 El cuerpo del texto, elegir un tipo de letra 105

fi nales libro comentarios 193-195


UN

UN DISTANTE VER 25, 42, 177 - 178 cmo leer xv


UN DISTINTO ACTIVIDAD 29, 161 - 164, 168, 170, 183, diagrama 186 Actividad 72 organizacin xiii-xiv
alcance xii
Desarrollo de software adaptativo 2
Ad-hoc Correcciones 167 do

ADYACENTE COLOCACIN 109 - 111 Agile La cmara, la captura de la informacin 143

Alliance 1, 205 FALLO DE CUIDADO y sombreado 70, 74, 108 - 109


actitud gil 193 El uso cuidadoso de variaciones de tipo 44, 70, 78, 106, 106 -
Desarrollo gil xiii, 1, 2, 3, 22, 35, 38, 144, 162, 107, la herramienta 109 CASE 143,

163, 176, 205 150, 153

y documentacin 3 Cell, separando 108


Manifiesto gil ix, xiii, 1, 2, 22, 38, 144, 167, 173, 176, Diagrama de clase 68, 71, 72, 83, 155, 206
182, 205 Cdigo, documentacin 126
Modelado gil 2, 3, 28, 30, 38 PROXIMIDAD CDIGO-COMENTARIO 126 - 127, 153
proceso gil 194, 205 PGINAS COHERENTE 111, 111 - gestin fi
Los ecosistemas giles de desarrollo de software 2, 3 guracin Con 112 143
Anlisis, con el cliente 37 Contenido 56, 62, 63, 88, 114, 131, 132, 135, 206
ANOTADO CAMBIOS 144 - 145 Descripcin de Gestin de contenido 17, 57, 88, 114, 131, 191
la arquitectura 72 formato independiente del contenido 132
Arquitectura, diseo de comunicacin 41 DOCUMENTACIN CONTINUA 82, 146, 165, 166 - 168,
ARCHIVO, beneficios 124 170, 175, 182, 185
Autor 7, 42, 43, 64, 97, 104, 120, 125, 140, 141, 144, Cookbook 32, 206
145, 146, 161, 164, 165, 168, 169, 170, 171, 172, Creador-Crtico 178 cristal 3
173, 175, 178, 184, 205
conocer la opinin 174, 177 requisitos de captura del cliente 36
mantener la credibilidad 42, 57
mltiple 144, 164 el aumento de la participacin 175

CRTICA DE CONSUMIDOR 38, 170, 175 - 177, 178, 188


222 ndice

entregable 206 portafolio 30


diagrama de despliegue 72 la preparacin para la impresin 138

Descripcin, la separacin de evaluacin 43 visin general que presenta 77

Diseo impresin 98, 107, 115, 128, 131, 138, 208


comunicado 41 vs impresin en lnea 128

razn fundamental 39 tratamiento 138, 206


documento de diseo 20, 31, 34, 39, 45, 48, 51, 53, 55, 58, productor 153
68, 79, 82, 83, 129, 136, 140, 153, 155, 166, 184, revisin 25, 165, 170-174, 174-175, 178, 187, 208
185, 189, 206 diagramas de intercambio 136

DISEO RAZN FUNDAMENTAL 34, 36, 39 - 40, 46, 57, 182, 185, 190 de diseo, lo que espec fi cacin 31, 34, 36, 40, 45, 47, 48, 49, 51, 140, 209
permite el cambio 39

Diagrama 70-72, 88 almacenamiento y recuperacin 149

integrando en el texto 109 estructura xiv, 64, 66-70, 74, 82, 165, 169
compartir documentos 136 modelo 97, 141, 147, 151, 209
utilizar en visin general 71 seguimiento de los cambios 144

uso de 70 elementos tiles 85


cmara digital, captura de informacin 143 DOCUMENTO DE ARCHIVO 82, 123 - 125, 126, 135, 137, 146,
Diversidad de los miembros 178 148, 149
Documento HISTORIA DEL DOCUMENTO 70, 76, 81 - 82, 85, 141, 146, 167
la asignacin de la responsabilidad 164 documento horizontal 27, 72, 120 - 123, 124, 126, 146,
y ejemplos 45 148, 149, 152, 156, 182
y varios autores 144 plantillas de documentos 94, 130, 132, 133, 139 - 142, 148, 156
circulacin 186 Documentacin 206
estructura de control 139
el control de versiones 145 alertar a los lectores 75

coordinar las aportaciones 165 distribuyendo recursos 161


la creacin de vista mltiple 133 y proyectos futuros 180
definicin 206 y otras actividades 168
diseo 39, 98, 100, 102, 104, 106, 107, 108, 109, y programacin 148
111, 206 archivado 124
diagramas y tablas 88 la captura de los requisitos del cliente 36
medio ambiente para la escritura 168 crear vistas adicionales 134
explicando la terminologa 79 requisitos de fi nir 29
enfoque 26 cdigo de documentacin 126

historia 81 asegurando un valor duradero 34

la identificacin de lectores 24 entorno para la creacin de 169


la identificacin de las versiones 81 explicando la informacin abstracta 44
invitando a los lectores 179 hacerse notar 179
enlace 78 ayudar a los nuevos empleados 40

haciendo flexibles 131 cmo hacer til 24


administracin 31 mejora de la calidad 170
en lnea xiv, 98, 107, 128, 129, 130, 131, 143, 153, 207 en forma de rbol 121

involucrando al cliente 175


ndice 223

relevancia a largo plazo 35 Retroalimentacin, cmo obtener 177

mantener la atencin 26 ALGUNOS INSTRUMENTOS 139, 142 - 144, 156

mantenimiento de la infraestructura 147 Centrarse en la pertinencia LARGO PLAZO 33, 34 - 36, 40, 57,
hacer accesible 66 168, 182, 190
haciendo interactivo 125 La informacin centrada 25, 26 - 27, 34, 44, 70, 79, 123,
minimizando el esfuerzo 142 137, 175, 185 fuentes

visin general que presenta 120 206

la preservacin de las versiones 123 eleccin para el nfasis 106, 107


procesos y planes 182 elegir 104
cartera de proyectos 31 tamao 100

papel de 2 estilo 107


la especificacin de requisitos 28 uso de serif 105
estructura y legibilidad 61-64 hojas de formato y estilo 132
uso de referencias 78
cantidad vs utilidad 4 independientes del contenido 132

frente a la comunicacin cara a cara 20


cundo escribir 166 GRAMO

DOCUMENTACIN PORTAFOLIO 27, 29, 30 - 34, 36, 45, 47, 163 GLOSARIO 25, 70, 79 - 81, 86, 141 Glosario, el valor en
la documentacin 80
Dominio, explicando la terminologa 80 DIRECTRICES PARA LOS LECTORES 25, 70, 72, 75 - 76, 78, 80, 82,
86, 123, 141 Directrices, su uso en la
mi documentacin 76
El nfasis, en el texto 106, 107
atraer a los clientes 38 MARIDO

Ejemplo proyecto AirView 16, La partida, la eleccin de un tipo de letra 105

47, 190 HTML 132, 133, 134, 135, 150, 207


Contentis 17, 57, 191 editor 143
Librar 13, 47, 90, 188 hipertexto 66, 121, 207
Flexicar 16, 48, 58, 153, 189
Navegador 15, 51, 155 yo

Puertas abiertas 17, 55, 187 IMPORTACIONES POR REFERENCIA 136 - 137, 148, 149

Paracelso 12, 46, 156 REQUISITOS DE DOCUMENTACIN INDIVIDUALES 28 - 30, 33,


persistor 14, 47, 50, 58, 88, 153, 184, 191 49, 144, 163 Material de

Vista 14, 53, 154, 186 informacin abstracta 44

Webber 12, 56
Ejemplos, valor de 45 abstrayendo 75

informes de la experiencia 46-59, 82-91, 112-114, 149-157, hacer accesible 66


182-191 visin general que presenta 77

Expertos al alcance del odo 21 La la presentacin sistemtica 73

programacin extrema 2, 28 Marketplace Informacin 36, 126, 179 - 180, 188, diagrama 190
Interaccin 32, 72, 206, 207
F Imagen introductoria 131
Comunicacin cara a cara xi, 3, 19, 20, 22, 34, 36, Seccin introductoria 131
37, 50, 55, 57, 64
224 ndice

JUICIOSO ESQUEMAS 42, 70, 70 - 72, 82, 88, 144 Pgina evitando roturas 111

K optimizacin 111
Conocer al cliente captura de 176 espacio para el texto 98, 99
Conocimiento 35 formato de prrafo 141, 144, 207
lenguaje de patrones 5, 6
extraccin y transferencia de 181 Patrones y experiencia de dominio 6
administracin 31, 181, 182
conservacin xi, 57, 189 ms recursos 7
reutilizacin 30 en la arquitectura 6
transferir 3, 24, 48, 181 estructura 8
CONOCIMIENTO ADMINISTRACIN 36, 180, 180 - 182, 190 Qu son? 5
PDF 139, 144, 150, 153, 208
L lector PDF 143
Diseo 93-114, 207 Formato de Documento Portable 139, 144, 150, 153
haciendo flexibles 131 Posdata 139, 208
uso de estilos 132 Imprimir documento 98, 107, 115, 131, 138, 208
Desarrollo magra 2 formato de impresin 138, 139, 208
Legibilidad xiv, 93, 94, 97, 98, 102, 105, 106, 107, 108, Proceso, presentando visin general 70
115, 207 Programacin y documentacin 148
Lnea Proyecto de diseo de la comunicacin 41
separacin ptima 102, 103
anchura ptima 100, 101 comunicaciones dentro del equipo 125
Escuchar, escuchar, escuchar 176 credibilidad 57
De poca profundidad rboles de documentos 131 requisitos de documentacin de fi nir 29
Resumen de la documentacin 120
METRO
alcance la documentacin 30
documento de gestin 31 documentar estados estables 167
analista mercenaria 178 hacer que la gente a la velocidad 40
Meta-informacin 207 la proteccin de la documentacin 123

espec fi cacin 37
norte
Proyecto AirView, la experiencia 47, 190
NOTIFICACIN SOBRE ACTUALIZAR 145 - 146, 149, 179
Proyecto Contentis, la experiencia 57, 191
Proyecto liberarse, la experiencia 47, 90, 188
O
Proyecto Flexicar, la experiencia 58, 153, 189
UNO RESPONSABLE AUTOR 126, 145, 164, 164 - 165, 168,
Proyecto Flexicar, la experiencia 48
175, 185, 186 documentos on-line xiv, 98, 107, 128, 129, 130,
Navegador de proyectos, la experiencia 51, 155
131,
OpenDoors proyecto 64
143, 153, 207
OpenDoors de proyectos, experiencia 55, 187
Propietario por entregable 165
Proyecto Paracelso, la experiencia 46, 156
La experiencia del proyecto persistor 47, 50, 58, 88, 153, 184,
191
el panorama 52
ndice 225

proyecto Vista El sombreado, el uso de 108

entorno de las aplicaciones 54 FUENTE NICA Y OBJETIVOS DE MLTIPLES 130, 132, 133 -
experiencia 53, 154, 186 135, 148, 149, 154 proyectos
Proyecto Webber, la experiencia 56 de software 208
ESPECIFICACIONES como un esfuerzo conjunto 34, 36, 36 - 39, 45, 51, documento de
Q cationes 80 Speci fi 31, 34, 36, 40, 45, 47, 48, 49,
La calidad, de los documentos 170

51, 140, 209


R Hoja de clculo 90, 143, 154
Legibilidad xiv, 69, 208 Diagrama de estado 72
optimizacin 111 Paso a paso 194 Estructura, descripcin que
Lector 208 presenta 70
y versiones correctas 145 La informacin estructurada 27, 44, 66 - 70, 72, 74, 78, 82,
la identificacin de objetivos 24 107, 109, 112
instrucciones a 76
MEDIA de fcil lectura 79, 98, 122, 127, 128 - 131, 152, T
153, 168 Mesa 88
REALISTA EJEMPLOS 25, 39, 40, 41, 44 - 46, 58, 175 Refactoring 13, diseo 108
20, 21, 49, 185, 187, 208 integrando en el texto 109
Referencia, el uso en la documentacin 78 compartir documentos 136
REORGANIZACIN EN SOLICITUD 135, 137, 142, 147 - utilizar para presentar los datos 74
149, 154 lectores de destino 24 - 25, 27, 29, 33, 36, 46, 49, 76, 79,
De recursos, la asignacin de la documentacin 161 122, 175, 178, 180, 188 Plantilla 97,
revisin 25, 42, 47, 48, 57, 165, 187, 208 141, 147, 151, 209
cultura 7 y la estructura 140
proceso 7 Terminologa, explicando 79
tipos 178 texto enfatizando 106, 107
el material sin revisar 188
REVISIN ANTES DE ENTREGA 164, 165, 170, 174 - 175, 185, 188 espacio en la pgina 98, 99

el uso de bloques de construccin 68


REVISIN CULTURA 42, 164, 168, 170, 170 - 174, 177, 178, uso de estilos 132
182, 187 TEXTO EN 50% De una pgina 98 - 100, 102, 112
Crtico, la eleccin 177 EL PANORAMA 25, 34, 36, 40 - 42, 52, 53, 72, 88, 182, 185 Miniatura 209
Gobernante, el uso de 108

S patrn 197-204
Alcance del libro xii utilizar en la documentacin 77
Mel 2 Thumbnail Sketches 70, 76, 77 - 78, 79, 85, 107 de la herramienta, la eleccin 142
SEPARACIN DE Contenido y disposicin 131 - 133, 135,
141, 144, 148 Referencias trazable 70, 78 - 79, 86 Tutorial 32,
SEPARACIN DE DESCRIPCIN Y EVALUACIN 42 - 44, 209
57, 74 Dos alfabetos POR LNEA 100, 100 - 102, 104
SEPARACIN DE Procesamiento e impresin 138 - 139, dos tipos de letra 100, 104 - 106
144, 148
226 ndice

tamao de letra 101, 102, 103, 104, 105, 209 documentos de seguimiento 145

Tipo de letra 101, 102, 103, 105, 106, 108, 139, 206, 207, 209 Ver, del documento 133

y la longitud de la lnea de 101 W


elegir 104 navegador web 143, 207

Tipografa 70, 93-114, 209


contenido 17, 18, 56, 62, 63, 88, 191
T sitio 7, 12, 13, 17, 53, 56, 67, 125, 131, 143
diagrama UML 51, 71, 72, 82, 170, 206, 207, 209 WIKI 122, 125 - 126, 150, 180, 182 Procesador de textos xiv, 94, 97, 103,
AMBIGEDADES MESAS 44, 70, 73 - 74, 85, 89, 109 Uni fi Proceso ed 33, 104, 110, 112, 130,
209 132, 133, 134, 137, 138, 140, 143, 144, 145, 209, 210
ARRIBA 33, 209

caso de uso 17, 32, 33, 38, 39, 40, 45, 47, 57, 71, 210 ESCRITURA Y REFLEXIN 164, 168, 168 - 170, 182, 189 escritura, el medio
ambiente 169
V
Versin x
identificar 81 XP 2, 28

You might also like