• Categories
• Ingeniería de software
• Software
• Libros
• Calidad (Negocios)
• Información

Citation preview

Documentación ágil

Documentación ágil Una guía del patrón de

La producción de documentos ligeros para Proyectos de Software

Andreas Rüping

Copyright © 2003 por John Wiley & Sons Ltd, el atrio, Puerta del Sur, Chichester, West Sussex PO19 8SQ, Inglaterra Teléfono (+44) 779 777 1243 E-mail (para pedidos y consultas de servicio al cliente): [email protected] Visita nuestra página inicial en www.wileyeurope.com o www.wiley.com

Todos los derechos reservados. Ninguna parte de esta publicación puede ser reproducida, almacenada en un sistema de recuperación o transmitida en cualquier forma o por cualquier medio, electrónico, mecánico, de fotocopiado, de grabación, de exploración o de otra manera, excepto bajo los términos del Derecho de Autor, Diseños y Patentes de 1988 o bajo los términos 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 electrónico a [email protected], o por fax al (+44 ) 1243 770620.

Esta publicación está diseñada para proporcionar información precisa y fidedigna relacionada con el tema en cuestión. 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 también publica sus libros en una variedad de formatos electrónicos. Parte del contenido que aparece en la impresión puede no estar disponible en los libros electrónicos.

Biblioteca del Congreso de datos Catalogación en la Publicación

Rüping, Andreas. documentación ágil: una guía patrón para la producción de documentos ligeros para proyectos de software / Andreas Rüping. pag. cm.

ISBN 0-470-85617-3 (Papel:. Alq papel) 1. Los sistemas de fabricación flexible. 2. El diseño del sistema. I. Título. TS155.65.R87 2003

005.1'5-DC21

2003011756 Catalogación Biblioteca Británica de datos de publicación Un registro de catálogo de este libro se encuentra disponible en la Biblioteca Británica

ISBN 0-470-85617-3 Compuesta en Garamond Luz y Frutiger por WordMongers Ltd, Treen, Cornualles TR19 6LG, Inglaterra impreso y encuadernado en Gran Bretaña 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 producción de papel.

Contenido

Prefacio

ix

Prefacio

xi

Expresiones de gratitud

Introducción

xvii 1

antecedentes del proyecto

11

1 Encontrar los temas correctos

19

Los lectores de destino

La información centrada

Requisitos de documentación individuales Cartera documentación Centrarse en a largo plazo Relevancia Especificación como un esfuerzo conjunto Fundamentos de diseño

El panorama La separación de descripción y evaluación Los ejemplos realistas Informes de experiencia

24 26 28 30 34 36 39 40 42 44 46

Contenido

vi

2 Estructuración de documentos individuales La información estructurada

Diagramas juiciosas Tablas sin ambigüedades Directrices para los lectores

Thumbnail Sketches Referencias trazables Glosario Historia del documento

Informes de experiencia

61 66 70 73 75 77 78 79 81 82

3 diseño y la tipografía

93

Texto en el 50% de una página

98 100 102 104 106 108 109

Dos alfabetos por línea 120% Interlineado dos Tipos de letra El uso cuidadoso de las modificaciones de tipo

Sentencia cuidado y sombreado La colocación adyacente Páginas coherentes

Informes de experiencia

4 Infraestructura y Organización Técnica Paisaje documento Archivo de documentos

wiki Código-comentario de proximidad

De fácil lectura-Medios Separación de Contenido y disposición

Fuente única y Objetivos Múltiples Importación por referencia

La separación de procesamiento e impresión

plantillas de documentos pocas herramientas

Los cambios anotado Notificación sobre la actualización

Reorganización a petición

111 112

117 120 123 125 126 128 131 133 136 138 139 142 144 145 147

vii

Contenido

Informes de experiencia

Gestión 5 y Aseguramiento de la Calidad Una actividad distinta

Un responsable Autor Documentación continua La escritura y la reflexión

revisión Cultura Revisión Antes de entrega Crítica de consumidor

Una vista distante

información del mercado Gestión del conocimiento Informes de experiencia

149

159 161 164 166 168 170 174 175 177 179 180 182

Observaciones finales

193

patrón de miniaturas

197

Encontrar los temas correctos La estructuración de los documentos individuales

Diseño y la tipografía Infraestructura y Organización Técnica Gestión y Aseguramiento de la Calidad

197 198 200 201 203

Glosario

205

referencias

211

Índice

221

Prefacio

Como dice Jerry Weinberg en su texto clásico La psicología de la Programación de Computadoras:

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

Nada en el manifiesto ágil ( http://agilemanifesto.org/ ) estados no hagas ninguna documentación ', pero ya que muchos desarrolladores tienen una resistencia genética a cualquier forma de escritura que no se expresa en un lenguaje de programación, se han estrechado el siguiente principio a sus pechos colectivos:

... hemos llegado a valorar: software de Trabajo más de una documentación completa y proclamado al mundo que la documentación 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 documentación. Yo sería el primero en admitir que el proyecto 777 y todos los demás que he visto primer plano se podrían haber hecho mejor. Podrían haber sido completado tan bien de una manera menos pesada. No sólo creo que siempre hay margen de mejora, pero también creo que hay que esforzarse continuamente para mejorar -

especialmente en proyectos de seguridad crítica. 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 añade valor - hay una necesidad de documentación. Yo voto por este último.

Prefacio

x

Ahora, sin embargo, nos enfrentamos al dilema - ¿qué significa eso en un proyecto ágil? ¿Puede un proyecto realmente seguir los principios ágiles y todavía producir documentación? Esta es la pregunta Andreas Rüping aborda en este libro. Andreas ha documentado sus experiencias de aventuras de proyectos exitosos y no exitosos con la documentación. Él comparte una serie de encuentros con diversos proyectos pequeños: a, vieja tecnología a gran nueva, que abarca los últimos 12 años. 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 montón 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 documentación es mejor que cara a cara, cuando en línea es mejor que la copia impresa, cuando diagramas son más útiles que el texto. En una discusión cercano y querido a mi corazón, que también muestra cómo los impactos de documentación del cliente. Toda esta información 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 orientación en una forma útil. Andreas proporciona información su fi ciente para que nosotros aplicamos esta orientación y se benefician de su experiencia. Esto es algo útil, práctico.

El libro sigue sus propios principios. Es ligero y presenta las ideas útiles sin tener que sobrecargar el usuario. Es fácil 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 consternación mientras leía algo sorprendente. He aprendido mucho leyendo este pequeño libro, y estoy seguro de que también lo hará.

Linda Rising

Prefacio

Si usted trabaja en la industria del software, usted sabrá que la documentación que juega un papel importante en muchos proyectos. Entre otras cosas, los documentos describen los requisitos del usuario, arquitecturas de software, las decisiones de diseño, código fuente y los problemas de gestión.

No puede haber una gran cantidad de valor en tales documentos. La documentación puede contribuir al éxito de un proyecto, facilitando la información necesaria a disposición 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 disposición 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 información. Estamos rodeados de mucha información, a menudo demasiado. Puede llegar a ser difícil 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 información específico fácilmente se pierden. Algunas cosas son también mucho mejor comunican cara a cara a través de documentos escritos. El exceso de documentación es tan malo como no hay documentación en absoluto.

También es difícil mantener los documentos al día cuando sus sujetos se someten a cambio. Conservación de los documentos al día es especialmente difícil cuando un proyecto está ocupado y muchas otras cosas requieren atención. Pero los documentos obsoletos pueden conducir fácilmente a los lectores equivocadas pista - documentos obsoletos a menudo hacen más daño que bien. Este libro tiene una ágil aproximación a la documentación - un enfoque que es a la vez ligero y su fi ciente, en la misma línea que los enfoques ágiles a

Prefacio

xii

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

Este libro presenta una colección de patrones - directrices que ofrecen soluciones a los problemas recurrentes aún múltiples caras de la documentación. Estos patrones se rigen por los siguientes principios generales:

•

La documentación del proyecto es más eficaz cuando es ligero, sin ningún tipo de documentos innecesarios, sin embargo, que proporciona toda la información relevante para los lectores.

•

Los documentos que se consideren necesarios sólo pueden resultar útiles si son de alta calidad: información precisa y actualizada, de fácil lectura y legible, concisa y bien estructurada.

•

Herramientas y técnicas son útiles sólo si facilitan la producción de documentos de alta calidad y hacer que su organización y mantenimiento más fácil.

•

El proceso de documentación 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 método estándar que pretende resolver todos los problemas asociados con la documentación del proyecto de software. En primer lugar, un procedimiento de este tipo es prácticamente imposible, ya que no hay dos proyectos tienen los mismos requisitos de documentación. En segundo lugar, un método de peso pesado es lo último que querría proponer - un fl integración global superó método de documentación 'estándar' sería demasiado inflexibles e implicaría demasiada burocracia para ser útil. Ciertamente, no sería ágil.

Este libro se centra más bien en los elementos y procesos que en repetidas ocasiones se pueden encontrar en buena documentación del proyecto, y que expresan una actitud ágil. Tales elementos y procesos se han formado en los patrones que se pueden utilizar para diseñar la documentación que fi cios de su proyecto individual mejor, y que contribuye a la experiencia realizada en su organización.

Alcance

Este libro está dirigido a personas que trabajan en la industria del software y cuyo trabajo incluye la redacción de la documentación del software en algún momento. Esto es cierto para la mayoría de los ingenieros de software, diseñadores, consultores y gestores. Si pertenece a alguno de estos grupos, entonces este libro es para usted. 1

xiii

Prefacio

Tal vez te gusta la documentación, o tal vez usted lo ve como una carga. En cualquier caso, este libro le dará consejos sobre cómo centrarse en lo que es importante en la documentación, se debe hacer que su proceso de documentación más e fi ciente, y que debería conducir a mejores resultados.

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

proyectos de consultoría también están dentro del alcance de este libro. proyectos de consultoría de colocar ligeramente diferentes requisitos sobre la documentación de los proyectos de desarrollo, ya que los proyectos de consultoría a veces tienen la documentación, en lugar de software, como el resultado del proyecto deseado. proyectos de consultoría puede bene fi ciarse de un enfoque ágil, ya que este planteamiento hace que el proceso de documentación más e fi ciente y los documentos resultantes más compacto y sencillo.

Organización Antes de presentar los patrones reales para la documentación ágil, este libro comienza con algunas observaciones preliminares sobre el desarrollo ágil y sobre los patrones. Si desea leer sobre la Manifiesto ágil y cómo se relaciona con la documentación, esta introducción será útil para usted. Si desea aprender qué patrones son y cómo se pueden utilizar, también encontramos respuestas en la introducción. Una sección que sigue describe brevemente los proyectos en los que se observaron los patrones en este libro. La colección real de los patrones se encuentran en los cinco capítulos principales del libro, cada uno de los cuales se ocupa de un tema en particular de la documentación del proyecto de software. Específicamente, los principales capítulos se refieren a las siguientes áreas:

1. Encontrar los temas correctos

La documentación es importante: algunos aspectos de un proyecto requieren documentación desesperadamente, mientras que otros no lo hacen. Entonces, ¿qué documentos son necesarios en su proyecto, y qué temas deberían 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 estándar, guías de instalación de software o similares, ni es el libro dirigido a la documentación que se produce por los escritores técnicos profesionales.

Prefacio

xiv

¿necesario? ¿Qué documentos son quizás innecesario? Este capítulo presenta algunas pautas sobre cómo Para averiguar qué documentación requiere su proyecto.

2. La estructuración de los documentos individuales

documentos bien estructurados dan a los lectores una mejor y más rápido acceso a la información de los documentos pobremente estructurados. Pero ¿qué aspecto tiene una estructura de documento como? ¿Cómo puede asegurarse de que sus lectores fi fácil encontrar la información que está buscando? Este capítulo ofrece sugerencias sobre cómo aumentar la legibilidad de los documentos del proyecto.

3. Diseño y la tipografía La legibilidad es una cosa, la legibilidad es otro. ¿Cómo se puede documentar la disposición apoyar la capacidad del lector para comprender el contenido de un documento de forma rápida y fiable? ¿Cómo puede una disposición tal puede lograr con los procesadores de texto estándar? Este capítulo le indica cómo mejorar la apariencia de sus documentos fácilmente.

4. Infraestructura y Organización Técnica En este capítulo se habla de cómo se puede gestionar sus documentos del proyecto. El capítulo comienza con las cuestiones de organización: ¿cómo se puede obtener una visión general de la documentación del proyecto? Se supone que los documentos se imprimen en papel? ¿Qué hay de documentación en línea, que se está convirtiendo cada vez más popular? La solución de esos problemas de manera rápida nos conduce a temas más técnicos: cómo se pueden procesar y almacenar documentos? ¿Cómo puede asegurarse de que los documentos individuales se pueden encontrar fácilmente? ¿Qué medidas deben tomarse para hacer la documentación del proyecto fácil de mantener? ¿Qué herramientas son necesarias para esto?

5. Gestión y Aseguramiento de la Calidad Los problemas de gestión de direcciones último capítulo como el presupuesto, responsabilidades y prioridades, en lo que se refiere a la documentación del proyecto. Las preguntas que debe hacer aquí son: ¿qué aspecto tiene un proceso de documentación e fi ciente similares, o, ¿cómo se puede evitar la burocracia? Siendo medios ágiles poniendo a las personas en primer plano, por lo que este capítulo se hace hincapié en el papel que juegan las personas en el proceso de documentación y subraya la importancia de la retroalimentación y reflexión.

xv

Prefacio

Cómo 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 visión rápida, sólo tiene que ir a través de cada patrón con rapidez y leer las secciones en negrita. Estos bocetos forma en miniatura que le dan una impresión general del patrón real. Además, un resumen de todas estas miniaturas se da al final del libro.

•

Leer los patrones completos si desea obtener una visión más profunda, y particularmente si usted está interesado en la lógica de los patrones individuales.

•

Comience con los informes de la experiencia, si desea tomar un viaje a través de varios proyectos del mundo real. Los informes explican cómo 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 visión general de lo que el libro tiene en el almacén, y leer los patrones completos cuando se convierte interesado en los detalles o en el fondo de un modelo. A continuación, puede utilizar las miniaturas como una lista de control cuando se trabaja en la documentación de su proyecto, utilizando los patrones completos cuando se trata de cuestiones más detalladas. Alternativamente, se puede comenzar con los informes de la experiencia, y seguir las referencias a los patrones individuales cada vez que sienta un patrón es de particular interés para usted. Si usted está interesado en algunos temas más que otros, puede concentrarse en los capítulos que son de particular interés para usted. Los punteros de vez en cuando se refieren a un material relacionado en otros capítulos.

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 páginas. Muchos de los patrones de fi cio en dos o tres páginas, y puede utilizar las imágenes 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 documentación de los proyectos de software. Me gustaría invitarle a este enfoque con el objetivo de hacer más eficaz la documentación para autores y lectores por igual. Estoy interesado en recibir sus comentarios sobre este libro. Si usted tiene algún comentario, no dude en contactar conmigo en [email protected] .

Andreas Rüping

Expresiones de gratitud

proyecto

Mis primeras ideas sobre la documentación ágil (aunque no me refiero a él como tal en el momento)

gracias

datan de hace varios años a un momento en que yo estaba trabajando en FZI (Forschungszentrum Informatik, Centro de Investigación de Tecnología de la Información) en Karlsruhe, Alemania. Durante un par de proyectos de investigación y varias colaboraciones industriales, he tenido la oportunidad de aprender mucho sobre lo que caracteriza a una buena documentación del proyecto. Pero no había más que esto: el espíritu de equipo entre el grupo me permitió disfrutar de esos años 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 Lötzbeyer, Achim Weisbrod, Helmut Melcher, Oliver Ciupke, Benedikt Schulz, Rainer Neumann, Artur Brauer, Jörn Eisenbiegler, Markus Bauer y Holger Bär.

Mi comprensión de una buena documentación se re fi ne cuando, unos años más tarde, me uní SD y software de diseño y gestión m AG, Alemania. Tuve la oportunidad de ver en la documentación producida en varios proyectos en los que participé. Muchos de los patrones incluidos en este libro me llamó la atención cuando se aplicaron con éxito en proyectos sd & m. Agradecimiento a mis colegas por ser un buen equipo, por la colaboración fructífera largo de muchos proyectos y para muchas discusiones interesantes. En los últimos años, EuroPLoP - la conferencia europea sobre patrones de software - ha sido un excelente foro para la discusión de todo tipo de temas en torno a los patrones, para mí y para los demás. 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 Schütz y Christa Schwanninger.

xviii

Expresiones de gratitud

EuroPLoP resultó ser particularmente útil cuando presenté documentos sobre diversos aspectos de la documentación. En primer lugar, me gustaría 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 harían en este libro. Por otra parte, muchas personas ofrecen información valiosa y un montón de buenas ideas en los talleres EuroPLoP. Son demasiados para nombrar en persona, pero su ayuda fue muy apreciado.

Un taller sobre 'Patrones de Gestión de Documentación Liviana' en la conferencia de OT 2002 en Oxford también 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 Völter y Egon Wuchner tomaron el tiempo de leer el proyecto, ofrecieron su visión 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 publicación. En primer lugar, me gustaría 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 también a Karen Mosman por su apoyo en la etapa temprana del proceso de publicación, a Jonathan Shipley para el cuidado de muchos detalles de la organización, y Juliet Booker por su trabajo como el editor de la producción. Por último, pero no menos importante, me gustaría dar las gracias a Steve Rickaby de WordMongers para la conducción suave a través de la etapa de corrección de estilo. Este fue un proceso muy agradable que dio lugar a un debate fructífero sobre el contenido, el lenguaje y el diseño del libro.

familia

Estoy feliz de reconocer que este libro tiene también 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 estímulo, apoyo y esos momentos de equilibrio que usted necesita cuando usted pasa por el proceso de escribir un libro.

Introducción

Ágil desarrollo

documentación ágil ha prestado su nombre de las ideas de Desarrollo Ágil de Software . 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 también 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 trabajaa sobre unaloamplia haciéndolo ayudando que otros hagan.documentación A través de este trabajo hemos llegado a valorar: colaboración con el cliente durante la negociación del contrato

Respondiendo al cambio sobre seguir un plan

características diferentes. Todos estos nos están descubriendo mejores formas de desarrollar software Es decir, mientras hay valor en los elementos de la derecha, valoramos los elementos de la izquierda más.

por varios métodos propuestos por diferentes personas, que se aplican en diferentes contextos y tienen

El manifiesto continúa con una serie de declaraciones más detalladas y recomendaciones concretas.

El desarrollo ágil no es un método especí fi co de desarrollo de software. El desarrollo ágil está compuesto

Introducción

2

métodos tienen en común, sin embargo, el hecho de que se centran en los valores fundamentales expresadas en el manifiesto.

Algunos de los métodos ágiles más 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 desempeña el trabajo en equipo en proyectos de desarrollo de software, y acerca de los problemas de comunicación que surgen en los proyectos de desarrollo de diferentes tamaños 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 visión 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 prácticas que conducen a la modelización eficaz y ligero, con especial énfasis en los aspectos humanos del desarrollo de software.

•

Programación extrema ( Beck 2000) fue propuesto por Kent Beck. XP, ya que generalmente se le conoce, es un método ágil centrada en la programación en su contexto social. XP da la bienvenida a los requisitos cambiantes y pone mucho énfasis en el trabajo en equipo.

•

Otro método es ágil scrum ( Schwaber Beedle 2001), presentada por Ken Schwaber, Michael Beedle y Jeff Sutherland, que dibujar en la importancia de la auto-organización y la reflexión.

•

María de Poppendieck

próximo libro sobre Desarrollo magra

(Poppendieck 2003) describe una serie de principios de pensamiento lean, dirigidas a líderes de desarrollo de software. A medida que el manifiesto ágil es todavía bastante nuevo, podemos esperar que los métodos más ágiles de desarrollo de software que surjan en un futuro próximo. ¿Qué papel juega la documentación en un proyecto ágil?

El papel de la documentación

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

3

Introducción

Esto no significa, sin embargo, que la documentación es generalmente poco importante o que la documentación no se estipule. Vamos a echar un vistazo a lo que los autores de algunos de los métodos ágiles tienen que decir acerca de la documentación:

•

Alistair Cockburn recomienda que la documentación sea 'la luz, pero su fi ciente' (Cockburn 2001). Se introduce el Cristal familia de metodologías, que está dirigido a proyectos de diferente tamaño y criticidad. los Cristal metodologías requieren documentación que se cree, ¡pero el proyecto individual decidir lo que la documentación debe consistir.

•

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

•

Jim Highsmith, en Los ecosistemas desarrollo ágil de software ( Highsmith 2002), nos advierte de no producir la documentación para el bien de la documentación, pero pide un equilibrio: 'Documentación, con moderación, ayudas para la comunicación, mejora la transferencia de conocimientos, conserva la información histórica, y ful fi ls gubernamentales y los requisitos legales'.

Mi opinión 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 documentación. En segundo lugar, pero suf-luz de la documentación deficiente es más accesible, y por lo tanto más útil, para un equipo que voluminosa documentación. Creo que Scott Ambler hace la pregunta correcta: '¿Qué le gustaría tener, un documento sistema de 2.000 páginas que es probable que tenga un número signi fi cativo de errores en el mismo, o una de 20 páginas, visión general de alto nivel' (Ambler 2002)

Ciertamente, la documentación detallada a veces es necesario, pero por lo general los documentos más concisos y accesibles resonar más entre los lectores. Detalles menudo cambian más rápidamente que la documentación puede ser actualizado, y se comunican mejor cara a cara. (Hay más en escritos, en lugar de cara a cara, la comunicación al comienzo del capítulo 1.)

Introducción

4

utilidad de la documentación

cantidad de documentación

Figura 1. La utilidad de documentación

La Figura 1 demuestra la relación entre la cantidad de documentación y su utilidad. Más allá de un cierto punto, la utilidad de la documentación disminuye cuando se añade más información, porque hallazgo información relevante se vuelve más y más di fi culto como la cantidad total de los aumentos de documentación. Creo que puedo resumir esto diciendo que la calidad es más importante que la cantidad en la documentación 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 más contribuyen a la comunicación en un equipo de proyecto. El esfuerzo que se puede ahorrar mediante la producción de ligero documentación 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 impresión de que, en un contexto ágil, no sólo es la documentación ligera preferencia sobre una amplia documentación, sino también 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 propósito, de lo contrario no tomar la decisión 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'.

5

Introducción

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

Patrones

¿Cuáles son los patrones? Dejame explicar.

Este libro se ocupa de una variedad de preguntas acerca de la documentación. ¿Qué documentación es necesaria y útil? ¿Qué temas deben ser cubiertos? ¿Cómo deben estructurarse documentos individuales? ¿Cómo puede la documentación del proyecto en su conjunto se organizará, y qué herramientas son necesarias para hacerlo? ¿Cómo se puede organizar el proceso de documentación?

Si usted ha sido responsable de los aspectos de la documentación 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 documentación de un proyecto de software se enfrenta a ellos una y otra vez.

Acecho detrás de estas preguntas son problemas recurrentes que tienen soluciones recurrentes. Estas soluciones se repiten, o patrones, se pueden utilizar como directrices para la documentación de los proyectos futuros. UN patrón en este sentido es esencialmente un bien probada par problema-solución, 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 patrón es un poco más que esto. Un buen patrón también describe la efectivo que están asociados con un problema - todos aquellos temas que influyen o limitan las posibles soluciones. Un patrón por lo tanto, no sólo se presenta una solución, sino que también ofrece la razón de ser de esa solución. Por último, los patrones normalmente no están solos. Un solo patrón resuelve ningún problema, pero cuando nos acercamos a un tema en su totalidad, más 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 están relacionados difiere. Algunas colecciones de patrones están relacionadas de forma flexible y toman la forma de un catálogo, mientras que otros están más fuertemente entrelazados. En este último caso, hablamos de una

lenguaje de patrones .

Introducción

6

experiencia en el dominio de varias disciplinas ha sido descrita con forma de patrón: •

La idea de los patrones surgió originalmente de la arquitectura. El arquitecto Christopher Alexander acuñó las frases

'Patrón' y 'patrón

idioma'. Se utiliza patrones para capturar la experiencia de un siglo en la construcción de ciudades y casas (Alexander Ishikawa Silverstein 1977, Alexander, 1979).

•

La idea se hizo popular en la ingeniería de software a principios de 1990. El libro primer patrón de fi ganar mucha atención fue el libro sobre orientado a objetos

Patrones de diseño por Erich Gamma, Richard Helm, Ralph Johnson y John Vlissides - la 'banda de los cuatro'. Este libro incluye un catálogo de modelos que describen diseños orientados a objetos reutilizables (Gamma timón Johnson Vlissides 1995).

•

Desde mediados de 1990, una serie de libros de Patrón-Oriented Architecture Software ha cubierto varios aspectos de la ingeniería 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 organización. Su

Desarrollo generativo-Proceso lengua del patrón ( Coplien 1995) abarca la gestión de organizaciones y proyectos, con énfasis en diversos aspectos del trabajo en equipo. •

libro de Martin Fowler en Patrones de análisis cubre análisis de requisitos y modelado analítico (Fowler 1996).

•

Software de memoria pequeña 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 Völter, Alexander Schmid y Eberhard Wolff presenta las pautas de la construcción de infraestructuras de componentes del lado del servidor (Völter 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 gestión de proyectos (Cockburn 1998).

•

Mary Lynn Manns y Linda Rising plan para publicar un libro de patrones de La introducción de nuevas ideas en las Organizaciones ( Manns Rising 2003).

7

Introducción

•

Más patrones se han creado para describir diversos aspectos de la ingeniería de software, incluyendo el análisis, la arquitectura y el diseño, la gestión y la enseñanza. Muchos han sido publicados a través de los libros de la serie patrones (PLoPD 1995, 1996, 1998, 2000) oa través de las actas de la conferencia de EuroPLoP, la conferencia europea sobre patrones de software (EuroPLoP 1998, 1999, 2000, 2001).

•

Linda Rising publicó una patrón 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).

•

Más recursos sobre los patrones están disponibles a través del sitio web del Grupo de Hillside ( www.hillside.net), un t fi organización 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 años a partir de varios proyectos en los que participé. Ellos describen la esencia de lo que ha funcionado bien en la documentación producida en estos proyectos. Los patrones no se detienen aquí. La comunidad patrones pone mucho énfasis en la revisión de la cultura. La comunidad se ejecuta varias conferencias en las que se escriben los patrones, leído y discutido. Los autores reciben retroalimentación sobre los patrones presentados a través de un proceso llamado 'pastoreo' antes de la conferencia. En la conferencia, los patrones se someten a un proceso de revisión de sonido cuando son llevados a un taller de escritores. 2 Muchas personas ofrecieron comentarios y compartieron su visión 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 colección en su conjunto, sin embargo, es nuevo, y debe servir bien como una guía compacta.

2. Esta cultura opinión 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).

Introducción

8

Problema Problema Efectivo

discusión Efectivo

Problema

Solución

Efectivo

discusión discusión

Problema

Solución

Efectivo

Solución discusión

Solución

Figura 2. Patrones - directrices en forma estructurada

estructura de

Un gran beneficio de los patrones es que siguen una forma común, estructurado, que los hace fácilmente

patrón

accesible - una forma de patrón. La literatura patrón ha visto muchas formas diferentes, que van desde mayor medida estructural para más formas de prosa similar.

9

Introducción

A lo largo de este libro, utilizo la forma patrón ilustrado en la Figura 2:

•

Cada patrón se inicia con una breve descripción del problema. Esta declaración consta de una pregunta que se introduce en el problema.

•

Lo siguiente es la sección de las fuerzas que motiva por qué el problema es realmente un problema. La sección describe que las fuerzas tienen una influencia sobre las posibles soluciones. A menudo conflictivas fuerzas tirón en posibles soluciones y crear una tensión que la solución va a resolver.

•

La solución da una respuesta a la pregunta planteada en la sección de problemas. Comienza con una breve exposición de cómo el problema puede ser resuelto, y continúa con una descripción más detallada de esa pauta.

•

Por último, la sección de discusión le da alguna información adicional y describe las relaciones con otros patrones - en su mayoría otros patrones en este libro, aunque de vez en cuando hay conexiones a los patrones escritos por otras personas. 3

En conjunto, la sección de problemas y el primer párrafo de la solución fi forman una imagen en miniatura que hace posible que usted pueda obtener una idea del patrón rápidamente. La sección de las fuerzas, el resto de la solución y la sección de discusión ofrecen más detalles, información de fondo, y razón de ser.

3. Los nombres de patrón de patrones en el libro se ubican en pequeñas capitales, mientras que los patrones escritos por otras personas están en cursiva y tener una referencia a la fuente original.

antecedentes del proyecto

Antes de sumergirse en las pautas actuales, me gustaría tomar un breve vistazo a los proyectos de los que se extraen los patrones en este libro. Es más bien un conjunto diverso de proyectos, que van desde el desarrollo de software a la consultoría, a partir de la tecnología antigua a la nueva tecnología, desde pequeños equipos a los equipos grandes. Yo estaba involucrado en la mayoría 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 años:

•

FZI (Forschungszentrum Informatik; Centro de Investigación de Tecnología de la Información), Karlsruhe, Alemania, lleva a cabo proyectos de investigación, así como colaboraciones industriales, con una buena documentación es una parte natural de todos los proyectos.

•

SD y software de diseño y gestión m AG, Alemania, es una compañía de software que maneja proyectos en diferentes dominios de aplicación - proyectos de desarrollo utilizando todo tipo de tecnología, así como proyectos de consultoría. Documentación juega un papel importante en la sd & m, con un enfoque en la calidad más 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 divulgación de información privada, como las ideas de negocio y arquitecturas de software de propiedad de los clientes. También tuve que traducir algo del material original del alemán al Inglés. Además, presento los proyectos de forma anónima para evitar Discom fi ting cualquier organización. Los temas, la estructura y los efectos de ejemplo, los documentos son, sin embargo, la auténtica.

12

antecedentes del proyecto

proyecto Paracelso

Cliente

Una empresa alemana de software de tamaño mediano

Tipo

Desarrollo de software

Tema

elementos de construcción de un marco para la gestión de almacenes que el cliente pensaba vender a la industria farmacéutica.

Bases Técnicas UNIX, C ++ tamaño

6 personas más 2 personas de personal del cliente

Duración

1 año

Este proyecto eligió una especificación preparada por el cliente que detalla las interfaces de los componentes del marco debían ponerla en práctica. La primera tarea para el equipo del proyecto para llegar a un diseño, 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. Más tarde, el cliente hizo algunos cambios en los componentes cuando se utilizó el marco, de los que ahora eran una parte, en aplicaciones farmacéuticas reales.

proyecto Webber

Cliente

Una asociación científica

Tipo

Consultante

Tema

La introducción de la tecnología Web para el cliente, creación de un servidor Web y estructurar el sitio Web.

Bases Técnicas UNIX, Netscape Server, HTML tamaño

3 personas

Duración

6 meses

Este proyecto se llevó a cabo cuando la Web era todavía nuevo - a principios de la década de 1990. El cliente solicitó el apoyo para la creación de su nuevo sitio Web. El equipo del proyecto y el cliente se reunieron para una pequeña sesión de trabajo, en

13

antecedentes del proyecto

que se discutieron los contenidos y la estructura del sitio Web. Esto puso de manifiesto que el sitio Web se suponía que era un reflejo de la estructura jerárquica de la organización del cliente. El equipo de re define la estructura del sitio web, un servidor web instalado y puesto en marcha el sitio.

Después de que se complete el proyecto, el cliente desarrolló el sitio Web más allá y mantiene el servidor Web a sí mismos. proyecto extricate

Cliente

Una compañía de seguros alemana de tamaño mediano

Tipo

Reingeniería

Tema

Extraer información modificable sobre los productos de seguros desde el sistema de gestión de la política en una base de datos.

Bases Técnicas BS 2000, Windows NT, Cobol tamaño

8 personas más 4 miembros del personal del cliente; más personas del cliente involucrado temporalmente

Duración

2 años

El objetivo de este proyecto fue rediseñar un sistema de seguro de vida legado de mejorar su capacidad de mantenimiento. Esto implicó una transformación del modelo de datos, y una estrategia de migración para mover el sistema desde el modelo antiguo al nuevo. No se suponía que la funcionalidad de cambiar.

Antes de iniciar cualquier actividad de migración, el equipo tenía que entender cómo funciona el sistema antiguo. El equipo aprendió de los usuarios y documentado lo que habían 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 refactorización real a continuación, se llevó a cabo, la extracción de muchas de las propiedades no modificables en una base de datos.

14

antecedentes del proyecto

proyecto persistor

Cliente

Una gran compañía de seguros alemana

Tipo

Desarrollo de software

Tema

La construcción de un marco para el acceso de base de datos, incluyendo versiones objeto de la aplicación; la introducción del marco en varios proyectos.

Bases Técnicas BS 2000, CICS, DB2, Windows NT, Cobol, un Cobol OO extensión tamaño

6 personas, además de 2 personas de personal del cliente; cerca de 50 personas de otros 6 proyectos durante el análisis y la integración de los requisitos

Duración

2 años; integración con otros proyectos que se extiende sobre más de 2 años

Este proyecto se inserta en el contexto más amplio de otros proyectos relacionados que juntos desarrollaron varios sistemas nuevos para una compañía de seguros. El objetivo de este proyecto específico 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 diseñado como un marco, por lo que se podría adaptar individualmente por los proyectos que la utilizarían.

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

Cliente

Una gran compañía de seguros europea

Tipo

Consultante

Tema

Análisis del panorama de aplicación en la empresa del cliente y las relaciones entre los diversos sistemas de software; gestión de riesgos.

15

antecedentes del proyecto

Bases Técnicas Varios sistemas, COBOL, C ++, Smalltalk tamaño

2 personas; varios miembros del personal del cliente

Duración

8 meses

la organización del cliente opera un gran número de sistemas que implementan muchos procesos de negocio, utilizando una amplia gama de tecnologías. Algunos de los sistemas eran bastante nuevo, mientras que otros habían estado en uso desde hace casi veinte años. Todos estos sistemas trabajaron juntos, pasar los datos entre sí, llamar a las funciones y así sucesivamente. La comprensión 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 señalar los riesgos en la arquitectura general. Navegador de proyectos

Cliente

Un proveedor de software de automoción

Tipo

Desarrollo de software

Tema

La construcción de una interfaz gráfica de usuario para un sistema de navegación y comunicación del automóvil.

Bases Técnicas Windows CE; C ++ tamaño

8 personas

Duración

1 año

Este proyecto desarrollado varios componentes de interfaz de usuario para el que la especificación fue provista por el cliente. Los componentes se integran para formar una interfaz gráfica de usuario completa tal como se utiliza en los sistemas de navegación y comunicación que se encuentran en muchos coches.

El equipo diseñado y codificado los componentes, asegurando que podría ser con fi gurada para que coincida con diferentes 'apariencia' normas. Los componentes fueron probados bajo condiciones específico para sistemas embebidos.

dieciséis

antecedentes del proyecto

proyecto Flexicar

Cliente

Un fabricante de automóviles

Tipo

Desarrollo de software

Tema

Calendario de las etapas de producción automatizadas para el tiempo y la minimización de costos.

Bases Técnicas UNIX, Java, aplicación WebLogic Server tamaño

50 personas, entre ellos varios miembros del personal del cliente

Duración

2 años

Cuando se inició el proyecto, el cliente ya tenía una idea clara de los resultados esperados del proyecto. La fabricación de automóviles se compone de muchas etapas de producción: el cliente buscaba una programación automatizada de estos pasos, de manera que las máquinas de producción se utilizarían para la capacidad máxima, y ​por lo tanto todo el proceso de producción se volverían más rápido y por lo tanto menos costoso.

Los detalles de programación eran claras a los expertos, pero la implementación técnica representaron un gran reto. El equipo colaboró ​estrechamente con el cliente en una precisa especificación, y diseñó el sistema de cuidado, teniendo en cuenta aspectos tales como los requisitos de rendimiento y seguridad contra fallos. Una vez completada la aplicación, el cliente lleva a cabo el mantenimiento del sistema.

proyecto AirView

Cliente

Una compañía aérea europea

Tipo

Desarrollo de software

Tema

Interfaz de usuario para facturación de pasajeros.

Bases Técnicas Ventanas, C ++, Java, CORBA tamaño

30 personas; varios miembros del personal del cliente también participan

Duración

2 años

17

antecedentes del proyecto

El esquema de este proyecto era proporcionar una nueva interfaz gráfica de usuario para una aplicación de facturación de pasajeros. La funcionalidad en sí no sería cambiado. La interfaz de usuario tenía que cumplir con ciertos criterios ergonómicos. El proyecto comenzó con un análisis, llevado a cabo con el cliente, de los casos de uso típicos. Posteriormente, el equipo diseñado algunos elementos de la interfaz de usuario prototípicos 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 organización paraguas de una industria alemana

Tipo

Consultante

Tema

La selección de un sistema de gestión de contenido web.

Bases Técnicas UNIX, XML, HTML tamaño

3 personas, más 2 miembros del personal del cliente

Duración

3 meses

La organización del cliente buscaba un sistema de gestión de contenido web. El objetivo del proyecto era apoyar a la organización con la elección de un sistema que encajar sus necesidades. primera tarea del equipo fue analizar cuáles 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 organización. Un catálogo de criterios emergió del análisis de procesos que el sistema de gestión 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 recomendación del sistema que cumplía con los requisitos del cliente mejor.

Proyecto Puertas abiertas

Cliente

Una empresa en la industria fi nanciera

Tipo

Desarrollo de software

Tema

Diseño e implementación de una arquitectura Web.

18

antecedentes del proyecto

Bases Técnicas

J2EE, JSP, Servlets, EJB, servicios web

tamaño

50 personas, entre ellos varios miembros del personal del cliente

Duración

2 años

El cliente intención de crear una arquitectura de software basada en Internet que les permitió llevar a cabo el comercio electrónico a través de Internet. El objetivo del proyecto fue la creación de un portal a través del cual los bancos pueden acceder a información sobre los productos de seguros y vender estos productos a sus clientes. El proyecto consistía 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 más 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 podría integrar gradualmente más aplicaciones como su negocio exigió. Los equipos trabajaron en estrecha colaboración para crear un primer prototipo de trabajo del portal, a continuación, extender el portal y que sea más ampliamente disponible para los socios de negocios.

1 Encontrar los temas correctos La cantidad correcta de la documentación es exactamente la necesaria para el receptor para hacer su siguiente movimiento en el juego.

Alistair Cockburn (Cockburn 2001)

Hace un par de años, un colega mío se unió a un proyecto que había estado funcionando durante un tiempo. En su primer día, 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 contenían toda la especificación de una aplicación compleja. El director del proyecto estaba visiblemente orgulloso del hecho de que su equipo había producido tal documentación completa. Un par de horas más tarde, vi a mi colega sentado en su despacho, delante de una gran pila de papel, mirando bastante infeliz. Una pregunta acerca de cómo 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 cación”, y que no podía mantener a todos los detalles en su mente. Con el tiempo aprendió muchos de esos detalles, pero más de las discusiones con los otros miembros del equipo en las próximas semanas que la lectura de la documentación.

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 incluía todas las cosas útiles que debe saber sobre el proyecto, así como una lista de personas de contacto de diversas cuestiones. El colega comentó más adelante que este documento era muy útil para hacer su familiar con el proyecto.

En el primer incidente, la cantidad de información era simplemente demasiado grande. El nuevo miembro del equipo recurrió a cara-a-cara de la comunicación, que es lo que el

20

Encontrar los temas correctos

director del proyecto debería 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 más cortos general, debe darse preferencia a los documentos más largos es un poco demasiado simplista, sin embargo. Recuerdo un equipo que tuvo que hacer un poco de refactorización y estaban felices de que un documento de diseño sustancial estaba disponible, ya que los diseñadores originales ya no estaban en el proyecto. Este documento fue bastante detallado, ya que incluía un análisis de las alternativas de diseño que los diseñadores originales habían considerado, y describe las razones para el diseño que habían escogido. El documento fue de mucha ayuda durante la refactorización, y evitó que el equipo de la exploración de opciones de diseño de los diseñadores originales ya habían rechazado por buenas razones.

Estas historias evocan la cuestión de por qué algunos documentos resultan ser útiles, mientras que otros no lo hacen. Al parecer, algunas cosas pueden ser comunicados a través de documentos muy bien, pero otros no pueden. Con este fin, es útil contrastar el papel de la documentación con la comunicación cara a cara. La siguiente tabla resume las características importantes de cada uno.

Comunicación cara a cara

Documentación

La interacción directa

ritmo determinado auto-Diferentes personas a

La comunicación cara a cara permite ciclos de preguntas y respuestas rápidas. Le preguntas algo, alguien contesta, usted pide de nuevo en un detalle

entender la información a diferentes velocidades. Muchas personas hallar todavía tienen preguntas cuando una discusión ha terminado - preguntas

específico, se obtiene una respuesta más 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 comunicación involucra a las personas

leer a su propio ritmo, que van y vienen a través del

de una manera muy directa.

material, ya que necesitan.

21

Comunicación cara a cara

Documentación

La comunicación no verbal Las personas no se

la comunicación introvertido Mientras que algunas

comunican a través de palabras exclusivamente.

personas les gusta participar en el debate, otros no lo

Una gran parte de la comunicación se lleva a cabo

hacen. las personas introvertidas son a veces

de una manera no verbal - a través 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 sólo a través de la comunicación

palabra más fácilmente 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.

Implicación personal

escalabilidad

Hablar el uno al otro significa llegar a conocer unos a

Los documentos pueden estar ampliamente

otros. La creación de confianza pasa mucho más rápido

disponibles. Puede hacer frente a un número casi

entre las personas que están en la misma habitación

ilimitado de personas a la vez. Por otra parte, los

que entre las personas que se comunican a través de la

documentos pueden llegar a los miembros de un

escritura solamente.

equipo distribuido - personas que trabajan en diferentes lugares.

rápida disponibilidad

En un proyecto bien organizado, hay Expertos al

disponibilidad a largo plazo Una vez que un proyecto llegue a su final el equipo se dispersa - expertos ya no

alcance del oído ( Cockburn

pueden estar disponibles. El software, sin embargo,

1998) fácilmente disponible para responder a las

todavía se necesitan un mantenimiento o incluso

preguntas que pueda tener. Las discusiones pueden

refactorización. Tan sólo aquellos documentos escritos

llegar en el calor del momento. Los documentos pueden

están disponibles más allá de los límites del proyecto real.

estar disponibles también, pero pasa el tiempo hasta que los documentos están escritos y puestos a disposición.

22

Encontrar los temas correctos

Por lo tanto cara a cara la comunicación y la documentación no se oponen entre sí. Tampoco es generalmente mejor o más eficaz que el otro. ¿Qué canal de comunicación es más apropiado siempre depende de la situación. O bien tiene sus ventajas, y ambos se complementan entre sí. Hay un montón 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 periódico y de hablar con nuestros amigos. Ni tampoco la comunicación verbal ni escrita es prescindible en una sociedad civilizada. No es de extrañar, por tanto, que los proyectos requieren tanto la comunicación cara a cara y documentación escrita. Intercambio de información ocurre con frecuencia en los proyectos de software, y sucede en contextos muy diferentes. documentación ágil pretende utilizar el tipo de comunicación que mejor se fi cios tales contextos.

Así contextos en los que se escribe la documentación recomendada? Volvamos al manifiesto ágil por un momento. El manifiesto dice que los individuos y la interacción, así como el software de trabajo, son algunos de los valores fundamentales de un proyecto de desarrollo ágil. Podemos concluir que la documentación es más valioso si contribuye a estos objetivos generales. En este sentido, la documentación es un medio, no un fin. Cuanto más ayuda a los individuos interactúan en un equipo, la documentación se vuelve más útil y más fácil 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 consultoría, sin embargo, la documentación puede ser el objetivo principal. Aunque los proyectos de desarrollo no están fuera del alcance del manifiesto ágil, podemos aplicar una actitud ágil a los documentos escritos en proyectos de consultoría también. Este libro no promete un fl integración global superó método de documentación. Proyectos difieren en gran medida y los requisitos de documentación difieren de un proyecto a otro. Por lo tanto, este capítulo 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 guían en su camino para de fi nir los requisitos de documentación especí fi co para su proyecto individual, y la determinación 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 capítulo.

23

apreciar la

SEPARACIÓN DE DESCRIPCIÓN Y

OBJETIVO LECTORES

EVALUACIÓN

La información centrada

apreciar

facilita

pregunta por

apreciar REQUISITOS DE

Centrarse en la pertinencia

DOCUMENTACIÓN INDIVIDUALES

mantener una

LARGO PLAZO

Puede elegir

EL GRAN IMAGEN

entre las

aprende

mantiene una

está en

PORTAFOLIO

de usos

sincronía con el

ESFUERZO CONJUNTO

sugiere una DOCUMENTACIÓN

sugiere para documentar la

servir como entrada

para el

ESPECIFICACIONES COMO

FUNDAMENTOS

ejemplos reales

DE DISEÑO

ayudar a explicar la

Figura 3. Patrones de hallazgo de los temas correctos

24

Encontrar los temas correctos

Los lectores de destino Problema

¿Cómo puede el equipo de proyecto asegurar que los documentos que producen será apreciado?

Efectivo

La documentación del proyecto se dirige a muchos lectores diferentes: gerentes de proyecto, arquitectos, diseñadores, programadores y usuarios. La gente en diferentes roles suelen tener diferentes perspectivas, y están interesados ​en diferentes aspectos de un proyecto de software. Los gerentes podrían no estar interesados ​en la lectura de un documento más técnico, incluso si son capaces de entender que, mientras que los programadores podrían no estar interesados ​en un resumen de gestión.

Por otra parte, diferentes personas a menudo tienen diferentes orígenes. El material puede ser sencillo para algunas personas y culto fi cultad para entender a los demás. 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 ningún uso.

Peor aún, la propia existencia de un documento es cuestionable si no está claro quién debe leerlo. Si la audiencia no puede ser nombrado, ¿cuál es el punto en la redacción del documento?

Solución

En primer lugar, cada documento debe tener un público 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 propósito para los lectores previstos.

Por ello, el primer paso es decidir, para cada documento, que son los lectores de destino. Estos pueden ser compañeros 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 explícitamente, preferiblemente cerca de la parte delantera.

•

Explicando qué información de fondo es necesaria para la comprensión del documento. Esto puede ser el conocimiento técnico o conocimiento del proyecto específico cs.

25

Los lectores de destino

•

No asumir más conocimiento de fondo que se puede esperar entre los lectores de destino.

•

Restringir el alcance del documento a lo que los lectores de destino esperarán. Esto ayuda a mantener la documentación corto y preciso, al igual que la restricción 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é información necesitan mis lectores' '¿Quién son mis lectores de destino', y '¿Cómo serán mis lectores ser capaz de entender?

Si la conclusión 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.

Discusión

Varios otros patrones ayudan a implementar este patrón. Dirigiéndose a los lectores de destino tiene mucho que ver con el mantenimiento de un foco: cuanto más se centró el documento es, más claro que puede hacer que el público objetivo. Presentación La información centrada le ayuda a permanecer en blanco. La inclusión de ejemplos reales y de un GLOSARIO hace que sea más fácil para sus lectores a entender lo que está diciendo.

Ciertos documentos de encontrar un gran número de lectores con facilidad. Por ejemplo, los documentos de información general entran en esta categoría - 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, dirigiéndose a ellos directamente es otra. los DIRECTRICES PARA LOS LECTORES al principio de un documento es el lugar perfecto para explicar quiénes son los lectores de destino y la información de fondo es necesario para la comprensión del documento. A veces es difícil imaginar lo que los lectores de material se puede esperar de un documento, y lo que los lectores serán o no ser capaz de entender. Si encontramos esto hace que sea difícil de definir el alcance del documento, se puede pedir a los demás para revisar el esquema del documento. Alguien desde fuera del proyecto tal vez puede tomar Una vista distante y proporcionar retroalimentación.

26

Encontrar los temas correctos

La información centrada Problema

Efectivo

¿Cómo se pueden prevenir los documentos de meandros y llegar a ninguna parte?

La documentación del proyecto en su conjunto a menudo aborda múltiples 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 cuánto 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 documentación del proyecto en márgenes razonables. Esto es deseable tanto para el equipo de proyecto que tiene que gastar recursos en la documentación, y para los lectores que deben tener acceso a información de forma rápida y fiable.

Sin embargo, la brevedad solamente no hace documentos fácil de usar. Otro aspecto importante es evitar la información 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 fácil para los lectores para identificar el documento que contiene la información que están buscando. En segundo lugar, evitar la información redundante hace que los documentos más fáciles de mantener y evita que se convierta en la documentación inconsistente. Evitar la información redundante también tiene inconvenientes. Si, en un intento de evitar la redundancia, también muchos aspectos se extraen en los documentos de su cuenta, los documentos resultantes serán menos autónomo. Los documentos se repleta de referencias a otros documentos, lo cual es contrario a la intuición a la lectura secuencial normal.

Solución

A fi cables enfoque claro e identi sobre un tema en particular hace un documento conciso y directo. El documento sencillo ofrece la información relevante a este tema, pero no más que eso. Por lo tanto, la información relacionada debe entrar en un documento separado si puede ser considerado para formar un tema de su propia, mientras que la información que es necesaria para la comprensión inmediata de un documento debe mantenerse dentro de él. Aquí hay algunas señales que indican si un documento tiene un enfoque claro:

•

Un documento debe ser apropiadamente titulado; un título claro sugiere que el enfoque del documento también está claro.

27

La información centrada

•

Las diferencias de alcance entre dos documentos relacionados deben ser claras de sus títulos.

•

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 atrás y preguntarse cuál es el propósito del documento es, y lo que tiene la intención de transmitir a sus lectores.

La consecuencia de este patrón es que a evitar información redundante hasta cierto punto, pero no del todo. Las pequeñas coincidencias entre los documentos son definir la medida en que son necesarias para hacer auto-contenida documentos. Este patrón no sólo se aplica cuando se configura un nuevo documento. Documentos evolucionan como un proyecto continúa, y es importante que no evolucionan en una masa detallado del texto, creciendo más allá de duración razonable. Cada vez que añade información a la documentación del proyecto, asegúrese de que la información entra en el lugar correcto, por lo que todos los documentos del proyecto mantienen su enfoque.

Discusión

UN CARTERA DE DOCUMENTACIÓN es un primer paso hacia la información centrada. Esta cartera se describen diversos tipos de documentos que puede necesitar un proyecto, y cuáles son sus contenidos son típicos. La cartera tiene en cuenta que cada documento tiene un grupo distinto de A quién va destinado. Se puede definir con precisión el foco de cualquier documento de la cartera, adaptándolo 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 comunicación. El más centrado los documentos individuales son, más clara será la Documento horizontal, y como consecuencia, el más eficaz es. información sobre el tema no sólo es deseable para los documentos completos, pero se puede analizar a nivel de capítulos y secciones de los documentos individuales. Esto es especialmente cierto para los documentos que se presentan La información estructurada - un formato que emplea elementos estilísticos para transmitir la estructura de un documento y su contenido.

28

Encontrar los temas correctos

Requisitos de documentación individuales Problema

¿Cómo se pueden evitar los requisitos de documentación innecesarios?

Efectivo

Hay proyectos de desarrollo que puede hacer con muy poca documentación. Los equipos pequeños que trabajan en un sitio se pueden hacer a menudo sin la documentación completa. Por ejemplo, XP (eXtreme Programming) es bien conocida por producir sólo un mínimo de documentación (Beck, 2000). Otros proyectos, sin embargo, requieren más documentación. Tal vez los interesados ​en el proyecto piden más documentación, tal vez el equipo necesita los documentos para la comunicación entre sitios, quizás necesita el diseño que se describe con más rigor que es posible usar sólo una discusión informal. La causa de los diferentes requisitos de documentación se encuentra en parte en las diversas metodologías 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 rediseñar los sistemas existentes. A veces diseñamos 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 consultoría pueden conectar diferentes significación a la documentación. En los proyectos de desarrollo, el valor de la documentación a menudo puede ser medida por lo bien que la documentación contribuye a la comunicación dentro del equipo. En los proyectos de consultoría, sin embargo, la documentación puede ser el objetivo del proyecto. En su libro sobre Modelado ágil, Scott Ambler escribe: 'Cada sistema tiene sus propias necesidades de documentación única; un tamaño no encaja todos', y recomienda: 'Que sea lo bastante simple, pero no demasiado simple'(Ambler 2002). En una línea similar, Alistair Cockburn, en su libro sobre Desarrollo Ágil

de Software, recomienda la creación de documentación que es 'la luz, pero su fi ciente' o 'apenas su fi ciente', y continúa: 'La cantidad ideal ‘apenas su fi ciente’, varía según la hora y el lugar dentro de un mismo proyecto.' (Cockburn 2001)

En otras palabras, si definimos un proceso de documentación estándar para todos los proyectos, y la fuerza de los equipos para crear todos los documentos que podrían ser útiles en cualquier un contexto, se impone una carga de trabajo de documentación innecesaria en muchos proyectos.

Requisitos de documentación individuales

Solución

29

El enfoque más eficaz para la documentación es para cada proyecto para definir sus requisitos de documentación de forma individual.

La cantidad real de documentación necesaria depende de factores como el tamaño 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 documentación de su proyecto en lo siguiente: •

La cantidad de documentación requerida por los interesados ​en el proyecto.

•

La cantidad de documentación que el equipo necesita para comunicarse.

•

La cantidad de miembros individuales del equipo de documentación que tenga que pensar en ideas a través.

•

La cantidad de documentación que el proyecto necesitará en una etapa posterior.

•

La cantidad de documentación necesitará probablemente un proyecto de seguimiento. Los

requisitos de documentación individuales deben de definir qué documentos son necesarios y qué material deben cubrir estos documentos. documentación ágil le invita a hacer sin ningún tipo de documentos que considere innecesario en una situación concreta, pero, por otro lado, para planificar activamente por los documentos que se necesitan.

requisitos de documentación pueden cambiar con el tiempo. Más documentación puede ser necesario, por ejemplo, hacia el final de un proyecto cuando el equipo pronto dispersarse. O menos documentación puede ser necesario, por ejemplo, durante las etapas de intensa colaboración en el que todos los involucrados puedan comunicarse fácilmente directamente. Re-evaluar los requisitos de vez en cuando es necesario para mantener la documentación en el nivel apropiado del volumen y detalle.

Discusión Elaboración de lo que la documentación del equipo o necesitan los interesados ​en el proyecto

está estrechamente relacionada con la elaboración de quién es el lectores de destino de documentos son posibles. La tarea real de de fi nir los requisitos de documentación debe ser parte de cualquier proyecto ágil. Si se piensa en la documentación como Un DISTINCT ACTIVIDAD, se puede de fi nir los requisitos de documentación y los recursos va a pasar en la misma forma que planea cualquier otra actividad del proyecto.

De fi nir los requisitos de documentación 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 podrían ser necesarios documentos y cuáles podrían ser sus contenidos.

A continuación, puede elegir los documentos que necesita y adaptarlos a necesidades específicas de su proyecto.

Cartera documentación Problema

¿Cómo pueden los equipos de reutilizar el conocimiento sobre la cual podrían ser necesarios documentos en sus proyectos?

Efectivo

No hay ningún punto de la hora de definir un proceso de documentación estándar o requisitos de documentación estándar 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 común. Por ejemplo, casi todos los proyectos de software hacen una diferencia entre lo que un sistema, un programa o un módulo hace, por un lado, y cómo sus componentes internos están diseñados por el otro. Esta distinción se debe a la 'ocultación de información' principio (Parnas 1972) y que a menudo se refleja en la documentación, lo que resulta en documentos separados para el sistema especí fi cación y el diseño del sistema. Hay otras categorías de documentos que se encuentran en varias ocasiones en la documentación del proyecto, que van desde documentos en las pruebas a los documentos que explican cómo utilizar el software. Muchos proyectos requieren documentos orientados a la gestión. A pesar de que estos documentos varían mucho en longitud y detalle, no hay ninguna razón para que cada proyecto debe reinventar las categorías de documentos que deben ser considerados cuando los requisitos de documentación son de fi nido.

Solución

Una cartera documentación describe los documentos que podrían ser necesarios en un proyecto de software, y su alcance. Si una organización establece dicha cartera, los proyectos pueden elegir aquellos documentos que necesitan, comprobando la necesidad de cada documento individual candidato. Una cartera de documentación 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 documentación que incluye los documentos candidatos para la mayoría de los proyectos de software. Una lista similar se da en el libro de Scott Ambler sobre Modelado ágil en el capítulo de la documentación (Ambler 2002). Usted puede

Cartera documentación

31

utilizar esta cartera, o se puede adaptar a las necesidades típicas de los proyectos de su organización.

Los documentos incluidos en el otoño cartera en las siguientes categorías: •

administración documentos definen el contexto de gestión para un proyecto, tales como el alcance global y la programación del proyecto. Un ejemplo típico es el resumen de gestión - un documento que describe los objetivos generales del proyecto y las pone en un contexto de negocios. documentos de gestión también pueden incluir un breve documento que introduce nuevos miembros del equipo para el proyecto.

•

Speci fi cación documentos describen lo que hace el software. Esto incluye aspectos tan extendida como datos, la funcionalidad, la interfaz de usuario, e fi ciencia y más. El propósito principal de los documentos fi caciones es aclarar exactamente lo que se necesita software. Especí fi cación documentos sirven como base para las discusiones con el cliente, o como base para la discusión con los equipos que trabajan en tareas relacionadas. Además, la especificación es lo que un sistema puede ser probado contra.

•

Diseño documentos explican cómo funciona el software, incluyendo por qué funciona de esta manera. Se ven en el funcionamiento interno de un sistema, un módulo o una clase, en su estructura y su comportamiento. Pequeñas solapamientos con la especificación son posibles - el modelo de datos, por ejemplo, es importante durante tanto especí fi cación y diseño. Los documentos de diseño se utilizan sobre todo para la comunicación entre el equipo de desarrollo, sino que también pueden ser útiles para la comunicación con el cliente interesado. Un documento de diseño puede ayudar a pasar en la experiencia del proyecto para futuros proyectos - un mecanismo de gestión del conocimiento que no debe ser ignorado.

•

Casi ningún 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 migración concepto necesario. Un concepto de migración se describe cómo la funcionalidad del sistema anterior da paso a la funcionalidad del nuevo sistema, y ​cómo 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

Gestión de proyectos •

Resumen de gestión

•

Plan de entrega

•

Proyecto directrices Manual / equipo

Requisitos especí fi cación

Diseño

•

Resumen del sistema

•

•

Los casos de uso

• Modelo de datos

•

Modelo de datos

•

jerarquía de clases

•

Funcional especificación

•

diagramas de interacción Clase

•

Interfaz de usuario específico de cationes

•

diseño de la interfaz de usuario / gestión de

•

comportamiento sincronizado

•

requisitos no funcionales (velocidad de ejecución, mantenimiento, etc.)

•

Introducción a la arquitectura

eventos

•

de acceso a la base de datos / transacciones

•

La integración con los sistemas vecinos

•

Directrices y convenciones de nomenclatura

Glosario

Migración

Uso

•

la migración funcionalidad

•

•

Migración de datos

• Cookbook

Directrices de uso / conceptos

• Tutorial

Prueba

operaciones

•

Los casos de uso

• despliegue

•

Casos de prueba

•

pautas de las operaciones

•

prueba de concepto

•

Solución de problemas

Figura 4. Una cartera documentación

Cartera documentación

•

33

A menudo, las pruebas han de ser especi fi cado, tal vez usando prueba documentos. Estos pueden solaparse con la especificación. Los casos de uso, por ejemplo, caen en una u otra categoría (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 cación, y puede hacer que los documentos especí fi cación separados redundantes en algún grado.

•

Uso documentos describen cómo se pueden usar un sistema, módulo o clase. Ellos describen el uso de parámetros, por ejemplo, y el orden en que las funciones pueden verse, y con frecuencia son necesarios para la integración de sistemas. documentos de uso pueden llegar a ser no más 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 atención, ya que aconseja a los usuarios cómo crear una aplicación de trabajo.

•

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

Muchos de los documentos mencionados anteriormente son bien conocidos de la literatura sobre la ingeniería de software (Sommerville, 1996) o de métodos de ingeniería 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 categoría en un solo documento. Tal vez algunos documentos son completamente innecesarios en su situación. Corresponde al equipo del proyecto para decidir qué documentación es necesaria en una situación específica, teniendo los requisitos del cliente en cuenta. Una buena dosis de escepticismo está bien cuando se trata de la decisión sobre qué documentos del proyecto deben ser escritos. desarrollo de software ágil nos anima a proporcionar la documentación que es necesario, pero ir sin papeleo innecesario.

Discusión

Se necesita la decisión 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.

Después de todo, qué conjunto de documentos que decida producir depende de la INDIVIDUAL REQUISITOS DE DOCUMENTACIÓN

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 información que es útil en el

34

Encontrar los temas correctos

a largo plazo y para producir documentos con alta significación. Por otro lado, la información que pronto será irrelevante probablemente no necesita ser documentada.

Visión general de documentos normalmente atraen el mayor número de lectores. resúmenes de gestión, 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 más importantes dentro de la cartera. documentos más detallados, sin embargo, están en el centro de la disyuntiva entre la comunicación verbal y escrita. Un documento fi especificación, por ejemplo, es típicamente el resultado de un análisis de requisitos. Se puede complementar las discusiones con el cliente, pero nunca puede sustituir a estas discusiones. (Ver también Especificación como un esfuerzo conjunto.)

Casi todos los proyectos necesitan un documento especi fi cación, pero no necesariamente

uno en el posible nivel de fi nido de detalle. Del mismo modo, la documentación de diseño es necesario y útil en la mayoría de los proyectos. En la mayoría de los casos, sin embargo, los documentos de diseño no tiene por qué estar preocupados con los detalles técnicos de bajo nivel, que se comunican mejor cara a cara. Los documentos de diseño en su lugar deberían centrarse en el FUNDAMENTOS DE DISEÑO - la motivación que llevó a las decisiones de diseño que el equipo ha hecho.

Por último, la clasi fi cación dada por la cartera de documentación contribuye al objetivo de presentar La información centrada.

Toscamente bocetos que documenta que pueda necesitar y describe cómo estos

documentos pueden centrarse en un tema en particular.

Centrarse en a largo plazo Relevancia Problema

¿Cómo pueden evitar la producción de proyectos de documentación que expira antes de tiempo?

Efectivo

documentación de los proyectos de software se ocupa de un conjunto más diverso de información. La información que se basan en los rangos de las especi fi caciones para el diseño, de los principios generales a los detalles técnicos, de equipo orientado a orientado al cliente. En un proyecto ágil, que no documentan de forma automática toda esta información por escrito. Un proyecto ágil evita gastar más recursos en la documentación de lo necesario, y se concentra en aquellos documentos que tienen un propósito claro que justi fi que el tiempo y el esfuerzo que entra en su producción.

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 comunicación escrita como medio de manera indiscriminada y sin tener en cuenta su adecuación. Estos factores conducen a la pregunta: ¿cómo 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 través de discusiones y la comunicación informal. Mucha de la información 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 información será relevante un par de meses o años más 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 preparación para futuros proyectos es un objetivo secundario que no debe ser ignorado (Ambler 2002). Esto es lo que significa Alistair Cockburn por 'preparación para el próximo 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 documentación puede desplegar su mayor beneficio: el conocimiento que debe ser preservada para el futuro es vale la pena documentar. Esto no es una mera suposición. la preservación del conocimiento ha sido objeto de mucha discusión y mucha investigación. Por ejemplo, Stuart Marca hace hincapié en la importancia de las bibliotecas digitales y no digitales en su libro sobre el pensamiento y la planificación a largo plazo, El Reloj del largo ahora ( Marca 1999).

Solución

Hay mucho valor en la documentación que se centra en cuestiones que tienen una importancia a largo plazo cuestiones que desempeñarán un papel en una fase posterior del proyecto o en proyectos futuros.

La documentación es esencialmente un instrumento para la gestión del conocimiento, tanto dentro de un proyecto ya través de proyectos:

•

Documentos, cuando describen los fundamentos de un proyecto, son importantes en todas las fases de los proyectos. Los ejemplos incluyen una especificación 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 diseño o conclusiones extraídas en una retrospectiva proyecto son todos los candidatos a la documentación escrita.

Hay menos valor en la documentación exhaustiva de las cosas sólo guarden relación 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 significación.

Discusión

Este patrón está estrechamente relacionado con el lectores de destino patrón. Ambos patrones plantean la cuestión de si la producción 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 DOCUMENTACIÓN. Existen varios ejemplos de documentos que típicamente se caracterizan por una relevancia a largo plazo y son casi siempre justificado: un documento que describe EL PANORAMA, un documento especi fi cación, siempre que el equipo realizó la ESPECIFICACIONES como un esfuerzo conjunto

con el cliente, y un documento para la FUNDAMENTOS DE DISEÑO. Si un tema tiene relevancia a largo plazo y debe ser documentado más allá de los límites 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 cuestión de gestión de la documentación, y se aborda en el INFORMACIÓN MERCADO y GESTIÓN DEL CONOCIMIENTO patrones.

Especí fi cación como un esfuerzo conjunto Problema

¿Cómo pueden los proyectos de desarrollo de asegurar que se dirigen en la dirección que el cliente quiere?

Efectivo

La especi fi cación de un sistema de software requiere una gran cantidad de las aportaciones de los expertos de dominio. Una estrecha colaboración 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 colaboración implica una gran cantidad de la comunicación cara a cara.

Sin embargo, es peligroso confiar en la comunicación 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 cación como un esfuerzo conjunto

37

usted puede pensar que ha llegado a un entendimiento común durante una discusión, pero cuando intenta confirmar su comprensión sobre el papel, que hallar este no es el caso. Una especificación escrita es mucho menos propensos a dejar que los malos entendidos pasan desapercibidos.

En segundo lugar, un documento escrito puede evitar disputas sobre quién tiene razón y quién está equivocado, debería diferentes surgen opiniones sobre los requisitos del sistema, quizás varios meses de iniciado el proyecto. Incluso la relación más amigable al cliente sufre cuando se hacen acusaciones de que el equipo diseñó el software equivocado. Una especificación escrita evita en gran medida tales acusaciones. Esto es aún más cierto cuando se trata de más de dos partes. Esto no es raro - a menudo varias compañías de software colaborar en un proyecto, y los diferentes departamentos de la organización del cliente también pueden tener una participación en el proyecto. En tal proyecto una especificación escrita da a todas las partes cierta seguridad de planificación.

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 especificación, pero la especificación debe dejar esto en claro, por lo que el equipo es consciente de las decisiones que aún se tienen que hacer. Cambiantes requisitos se consideran natural en un proyecto ágil que sigue un proceso de desarrollo iterativo. El documento especi fi cación ayuda a hacer frente a los requisitos cambiantes de una manera aceptable, la actualización del plan de proyecto y quizás plazos volver a programar en consecuencia.

Solución

Cada proyecto de desarrollo requiere una especificación, que re fl eje el análisis de necesidades realizado conjuntamente por el equipo del proyecto y el cliente.

Escribir la especificación debería ser mucho como mantener un registro de lo que se ha dicho durante la discusión de los requisitos. En ninguna parte es tan importante como en este caso que la comunicación y documentación de cara a cara se complementan entre sí:

•

El documento especi fi cación describe el entendimiento común del sistema que el equipo del proyecto y el cliente han conseguido, y proporciona el equipo con la información necesaria para comenzar el diseño.

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 cación. A veces, un su fi cientemente conjunto completo de casos de uso puede ser todo el documento especi fi cación 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 común.

•

El documento especi fi cación puede ser utilizado para obtener nuevas conversaciones comenzaron. Usted puede tomar un primer documento especí fi cación a los expertos de dominio para la retroalimentación, por lo que la mejora de la memoria descriptiva.

Es importante que todas las partes están de acuerdo en esta especificación. Esto requiere más que un acuerdo general de quien representa la organización del cliente en su conjunto. acuerdo de las partes interesadas requiere un entendimiento común compartido por el equipo y todos los departamentos de la organización del cliente, de hecho por todas las personas involucradas.

Discusión

Por mucho que este patrón hace hincapié en que una estrecha colaboración con el cliente es necesaria para producir una buena memoria descriptiva, no se debe llegar a la conclusión de que otros documentos no requerirán una colaboración similar. De hecho, todos los documentos del proyecto hacen. El punto aquí, y la motivación para este patrón particular, es que el catión requisitos especificados merece una especial estrecha colaboración entre el equipo del proyecto y el cliente desde el primer día. 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 días durante todo el proyecto', como se cita en el libro de Alistair Cockburn (Cockburn 2001). comentarios Alistair Cockburn: '... cuanto más tiempo se tarda en obtener información desde y hacia los desarrolladores, más daño se producirá al proyecto'. Scott Ambler cita la participación activa de los interesados ​como uno de los principios básicos de Modelado ágil

(Ambler 2002). El papel de la colaboración cliente también ha sido objeto de muchas otras obras. Por ejemplo, Jim Coplien, en sus patrones de organización, recomienda que se Atraer a los clientes ( Coplien 1995) no sólo en la garantía de calidad, sino también en las especi fi caciones y el diseño.

Aún así, la colaboración del cliente puede ser difícil, ya que requiere que usted pueda hablar un lenguaje común. Una manera de aliviar este problema es planificar para una CRÍTICA DE CONSUMIDOR.

39

Fundamentos de diseño

Además, hablando un lenguaje común es más di fi culto en abstracto que en el hormigón. Colaboración con el cliente puede fi nes mucho trabajando en REALISTA EJEMPLOS

a la que tanto el equipo del proyecto y el cliente puede relacionarse fácilmente. Esto es, entre

otras cosas, por qué los casos de uso son tan particularmente útil.

Fundamentos de diseño Problema

¿Cómo puede el equipo asegurarse de que se sientan las bases para futuros cambios de diseño?

Efectivo

La mayoría de los proyectos eligen para documentar el diseño del sistema que están construyendo. Un documento de diseño describe las interfaces del sistema, así como su funcionamiento interno, típicamente abordar tanto los aspectos estructurales y de comportamiento. El objetivo de dicho documento es transmitir el diseño del sistema a otros miembros del equipo, a los clientes o para proyectos futuros.

Tal descripción diseño 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 diseño real podría no ser su fi ciente. A medida que el diseño evoluciona, es importante que el equipo es consciente de por qué se eligió el diseño en el primer lugar y lo que podrían existir otras opciones de diseño. Sin embargo, los detalles de implementación 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.

Solución

Los documentos de diseño se convierten en una valiosa fuente de información, si no se limitan a describir el diseño actual, pero también se centran en la razón de ser del diseño y explican por qué se eligió el diseño particular.

Cuanta más experiencia revela un documento de diseño, más útil que puede ser para proyectos futuros. Se trata de las lecciones aprendidas del diseño del sistema que hace que un documento de diseño de una contribución valiosa a la documentación del proyecto. Esto conduce a las siguientes directrices:

•

El documento de diseño no sólo debe estar preocupado con los resultados del proceso de diseño, pero debe explicar las razones que llevaron al diseño real.

•

El documento de diseño debe explorar posibles alternativas de diseño, analizar sus pros y contras, y explicar por qué se rechazaron esas alternativas.

40

Encontrar los temas correctos

La razón de ser de un diseño 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 gustaría 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 diseño a menudo pueden prescindir de detalles técnicos de la codificación real.

Discusión

Este patrón está muy en sintonía con el deseo de poner una ENFOQUE EN EL LARGO PLAZO PERTINENCIA. Especí fi cos detalles de diseño pueden ser de poco interés después de un tiempo, y por lo tanto podrían no requerir documentación. El diseño general seguirá siendo esenciales años después de que el sistema se puso en marcha primero, sin embargo, y por lo tanto es un buen candidato para la documentación, junto con las razones que llevaron al diseño.

La explicación de los fundamentos de diseño puede obtener de forma significativa por el uso de REALISTA Ejemplos.

Los casos de uso, u otros escenarios, ayudar a explicar los principios detrás del diseño que

fue elegido, así como sus ventajas y desventajas.

El panorama Problema

¿Cómo se pueden introducir a la gente a un proyecto sin ser confrontado con un diluvio de información técnica?

Efectivo

Cuando la gente ve una pintura en una galería, a menudo paso atrás y mirar desde una corta distancia. Esto les permite ver la pintura como un todo. Si se encontraban justo en frente de ella, que sería capaz de ver el detalle, pero la impresión general se perdería. Por analogía, la documentación del proyecto a veces se ocupa de muchos detalles técnicos - especí fi cación detalles, detalles de diseño y similares. Estos datos pueden ser cruciales para el éxito del proyecto, y la documentación de ellos pueden ser útiles. Sin embargo, a veces es difícil ver el bosque por los árboles. En El hombre Mes Mítica, Frederick Brooks explica: 'mayoría de la documentación falla en dar muy poca visión 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 gustaría entender un concepto, o que necesitan para obtener una introducción en nuevos materiales .

El panorama

41

Sin embargo, la documentación también debe atender a las personas que aún 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 mantendrán un sistema una vez que se ha completado. Tales personas necesitan para conseguir una sensación para el proyecto antes de que puedan empezar a trabajar en los detalles.

Solución

Una buena idea de un proyecto es mejor transmite a través de una descripción de la 'gran imagen' de la arquitectura que subyace en el sistema en construcción.

Un documento de cuadro grande puede proporcionar una cierta comprensión general:

•

El panorama se describe la arquitectura general, muestra cómo todo el sistema se compone de subsistemas y módulos, y explica los conceptos básicos del comportamiento dinámico del sistema.

•

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

•

Los grandes nombres de las imágenes de la tecnología que es fundamental para la construcción del sistema.

•

El cuadro grande abstrae intencionadamente sobre cualquier detalle, técnicas o no, que son irrelevantes para una visión general.

Preferiblemente, un documento de cuadro grande debe ser bastante corto y conciso - un extenso documento no podía proporcionar la breve introducción que la mayoría de los lectores necesitan, y probablemente llegar a ser contrario a la intuición. Para la gran mayoría de los proyectos, 10 o como máximo 20 páginas son suficientes. El documento cuadro grande puede proporcionar enlaces a otros documentos más detallados, siempre que sea necesario, como ilustra la Figura 5.

Más allá de proporcionar una comprensión global, un documento panorama general es perfectamente adecuado para obtener las discusiones comenzaron. Principalmente debido a un cuadro grande es de interés general, sino también porque es normalmente corto, un documento panorama fi fácilmente lectores NDS. Si necesita tener una discusión con el equipo o con el cliente sobre cualquier problema relativo a la arquitectura general del sistema, pasar a la descripción de la gran imagen alrededor y que tiene un punto de partida perfecto.

Discusión

Este patrón muestra cómo puede proporcionar una visión general y sin perderse en los detalles técnicos. A pesar del deseo de brevedad, un cuadro grande de documentos a menudo utilidades de la inclusión 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 añadir valor a la gran imagen del documento si se toma la palabra imagen serio y proporcionar JUICIOSO ESQUEMAS REVISIÓN

que le ayudan a argumentar su caso. Toda la documentación se bene fi cios de una CULTURA

que otorga a los autores valiosos comentarios. Un documento que presenta el panorama general

puede beneficiarse especialmente de una revisión que se lleva Una vista distante, y por lo tanto se centra en la impresión general y no en los detalles.

La separación de descripción y evaluación Problema

¿Cómo pueden los autores evitar la pérdida de credibilidad?

Efectivo

En los proyectos de desarrollo, gran parte de la documentación del proyecto se ocupa de análisis, diseño, 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 conclusión, hacer una evaluación, o incluso llegar a su opinión personal. Tal vez, como ingeniero de software especializado y experimentado, se le solicita su opinión sobre un determinado

43

La separación de descripción y evaluación

diseño o un cierto concepto. Un documento de estrategia, por ejemplo, incluye típicamente puntos de vista personales y concluye con la recomendación del concepto c uno específico o estrategia.

Las opiniones personales son aún más comunes en los documentos que surgen de proyectos de consultoría. Si se trabaja en un proyecto de consultoría puede ser la parte central de su trabajo para llegar a una evaluación o una recomendación. 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 analogía, vamos a echar un breve vistazo a la esfera del periodismo. Es una buena regla de oro que usted debe dejar claro si un artículo en un periódico o una revista presenta hechos, o si se expresa la opinión del autor (Glasser 1992). Podemos adoptar esta regla de oro para nuestros propósitos. No es un buen estilo para tratar de influir en los lectores al confundir la descripción y el juicio -

Solución

lectores podrían poner en duda el contenido de un documento que parece ser sugerente.

Autores ganan credibilidad si, en sus documentos, que la descripción claramente separada de la evaluación. La siguiente tabla muestra más o menos cómo los diferentes tipos de información pueden clasificarse:

Descripción

Evaluación

Hechos

Juicio

observaciones

las opiniones del autor

Análisis

Recomendación

Datos

Validación

Estadística

Interpretación

44

Encontrar los temas correctos

La separación de la descripción y evaluación debe ser claro para los lectores. Hay varias maneras de lograr este objetivo:

•

La separación de la descripción y evaluación puede ser reflejada en la estructura del documento. Puede reservar ciertas secciones de un documento para el análisis, y sacar conclusiones o llegar a una recomendación en una sección separada.

•

Se puede utilizar técnicas de diseño, tales como cajas especiales, columnas adicionales, o variaciones de tipo para dejar claro a los lectores de que cierto material no es una descripción totalmente objetiva, sino que representa su opinión o las conclusiones que se dibujan.

Además, se puede dibujar en su dominio de la lengua para apoyar la separación de la descripción y evaluación. El material descriptivo no debe incluir implícitamente un juicio: adjetivos tales como bueno,

deseable, razonable, útil o malo, problemático, etc., deben usarse con cuidado al describir hechos u observaciones.

Discusión

La separación de la descripción y evaluación contribuye al objetivo general de la presentación CENTRADO INFORMACIÓN. El material presentado en un documento, o en una sección, se supone que tiene un enfoque claro. Una condición previa para un enfoque claro es no confundir la descripción y evaluación.

El uso de técnicas de diseño para apoyar la separación de la descripción y evaluación es particularmente útil cuando se elige para organizar documentos como ESTRUCTURADO INFORMACIÓN.

A continuación, puede emplear elementos estructurales, tales como bloques de texto

o dentro de las células TABLAS inequívoca, para visualizar la separación de descripción y evaluación. Del mismo modo, la El uso cuidadoso de variaciones de tipo puede hacer que la separación claramente visible.

Los ejemplos realistas Problema

¿Cómo puede explicarse abstracto material de una manera comprensible?

Efectivo

La mayoría de la gente trabaja mejor de lo concreto a lo abstracto que a la inversa. Material técnico, 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 más éxito cuando se acompaña de ejemplos convincentes.

45

Los ejemplos realistas

Por otra parte, los lectores son a veces escéptico cuando un documento sólo da consejos generales. Los ejemplos pueden proporcionar evidencia de que lo que se dice en un documento es información sustancial.

Sin embargo, los ejemplos 'juguete' pueden tener el efecto contrario en los lectores. Cuando un punto importante se explica sólo con un ejemplo de juguete, los lectores se les hace creer que el punto no es sustancial, y que una solución sugerida podrían no funcionar en casos prácticos.

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

Solución

Los documentos del proyecto son mucho más 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 aportación a un documento fi especificación. En algunos proyectos que pueden compensar toda la memoria descriptiva.

•

Al explicar un diseño técnico o la arquitectura del sistema, todavía es una buena idea que depender de ejemplos de casos de uso típicos. Esto hace que su explicación más fácil de seguir y demuestra que el diseño de su fuerza a los problemas correctos.

•

proyectos de consultoría no se refiere necesariamente a una tarea de desarrollo concreto y pueden no tener casos de uso concretos para confiar. ejemplos realistas son todavía útiles, tales como los escenarios típicos de dominio del problema.

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

Discusión

Este patrón se aplica a casi todos los documentos de la CARTERA DE DOCUMENTACIÓN. 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 también. Cuando se prepara un documento de diseño,

46

Encontrar los temas correctos

puede ilustrar la FUNDAMENTOS DE DISEÑO con ejemplos que demuestran las ventajas y desventajas de las alternativas de diseño 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 orígenes 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 gustaría presentar algunos informes de experiencias que muestran cómo se aplicaron los patrones de este capítulo 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 cómo

Requisitos individuales

diferentes los requisitos de documentación eran en estos proyectos. Por un lado, tener un proyecto de desarrollo tales como Paracelso. El equipo era pequeña y la colaboración con el cliente muy cerca. Todo el mundo sabía lo que estaban haciendo desde el principio, y contando con poca documentación había ningún problema. Los documentos producidos eran de peso ligero, en un sentido positivo.

Proyecto Paracelso: documentación mínima En este pequeño proyecto de la tarea estaba claro desde el principio: el cliente necesita ciertos componentes para la transformación de datos que se van a integrar en un marco que estaban construyendo. La estrecha colaboración surgió de forma natural. El equipo y el cliente decidió desde el principio que una mínima cantidad de documentación sería su fi ciente.

La especificación que se produjo consistía esencialmente en las notas que alguien había tomado durante un pequeño taller en el que el cliente explicó lo que se suponía que los componentes de hacerlo. Simultáneamente con el diseño y la codificación, el equipo elaboró ​un documento de diseño y un concepto de uso. El papel del diseño documenta las ideas básicas detrás de los componentes de transformación de datos. El documento fue puesto a disposición del cliente como entrada para un segundo taller, en el que el equipo y el cliente comprueba que el diseño de los componentes y el diseño de la estructura general eran compatibles, comenzó antes de la codificación. El concepto de uso proporciona información acerca de cómo podrían ser llamados los componentes, los parámetros que debían ser suministrado y así sucesivamente. El cliente utiliza este concepto mucho cuando se integran los componentes en su marco.

47

Informes de experiencia

Considere Proyecto AirView. El documento especi fi cación se centró en la definición de casos de uso. A medida que el equipo había elegido para construir un prototipo, una especificidad muy largo cación de la geometría de interfaz de usuario se hizo innecesaria. El equipo había entendido que la discusión de la interfaz de usuario utilizando el prototipo era mucho más eficaz que la producción de las especificaciones sin fin. Por lo tanto, la cantidad de documentación podría reducirse de forma significativa.

AirView Proyecto: GUI las especi fi caciones

El objetivo del proyecto era desarrollar una nueva interfaz gráfica 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 cación no debe incluir una fl integración global superó descripción de la geometría de interfaz de usuario. La especi fi cación de documentos de fi nen los casos de uso de la interfaz sería poner en práctica, pero intencionalmente en los detalles de la apariencia visual. La especi fi cación 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 comisión de los casos de uso de papel a clari fi cados muchos detalles.

Para describir la geometría de interfaz de usuario, el equipo en su lugar optó por construir un prototipo. Este prototipo actuó como un ser vivo especificación. Se le ha dado al cliente para revisión, podría ser adaptado rápidamente, y proporcionó gran parte de entrada, tanto más rápidamente y más concretamente de un resumen especificación podría haber hecho.

Por otro lado, algunos proyectos requirieron una documentación más detallada. Proyecto Flexicar (véase la página 48), por ejemplo, requiere una documentación más amplia debido a que muchas personas estaban involucradas, y porque estaba claro desde el principio que el mantenimiento del sistema con el tiempo sería entregado desde el equipo del proyecto para el cliente.

A continuación, hay Proyecto liberarse (véase la página 48). Este proyecto fue un gran esfuerzo de reingeniería. Una especi fi cación de lo que el nuevo sistema debe ser similar no fue suficiente. El equipo siempre tenía que seguir la migración del sistema antiguo al nuevo sistema en mente. Esta migración fue crucial para el éxito del proyecto, y que era necesario documentar, de manera que las numerosas partes interesadas podrían 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, más documentos de la CARTERA DE DOCUMENTACIÓN convirtió

48

Encontrar los temas correctos

Flexicar Proyecto: Descripción detallada del diseño Cuando se inició el proyecto, el cliente ya tenía una idea clara de cómo su proceso de fabricación de automóviles podría ser mejorado y acelerado. El equipo del proyecto era todavía pequeño en el momento, y produjo un documento general que resume los requerimientos del cliente. El documento también esbozó la arquitectura, el equipo tuvo en cuenta. El cliente revisó el documento, asegurando que el equipo se dirigía en la dirección correcta. El jefe de diseño a continuación, configurar un documento que describe la arquitectura del sistema con más detalle, re fi nir este documento como el proyecto avanzaba. Este documento fue bastante técnica, ya que estaba destinado principalmente para los ingenieros de software. El documento sirvió a dos propósitos. En primer lugar, se utiliza para comunicar los principios detrás de la arquitectura de todo el equipo. En algún momento, el proyecto consistió en un máximo de 50 personas, por lo que no podía basarse en la comunicación verbal solo. El documento de diseño facilita claramente el intercambio de conocimientos. En segundo lugar, el documento fue más tarde para ser utilizado por los miembros del equipo del cliente, que eran para mantener el sistema más 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 tenía que tener su opinión. En segundo lugar, ya que éste era un proyecto de reingeniería, el equipo primero tuvo que familiarizarse con el sistema antiguo y su dominio de aplicación.

El funcional especificación fue fácil: la funcionalidad del sistema no iba a ser cambiado en absoluto. El sistema tuvo que ser rediseñado para ser más 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 precisión se podían extraer en una base de datos. Esto implicó varios detalles sutiles e intrincadas, que fácilmente 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 habían pensado.

Un documento fi especificación fue de gran ayuda en cuanto a la detección de tales malentendidos se refiere. La especificación representaba lo que el equipo había entendido de los diversos productos de seguros, y se le dio a los expertos de dominio para su revisión. Los expertos en el dominio utilizan la especificación para verificar el mapeo de las antiguas propiedades, codificados de forma rígida a las nuevas propiedades. Los debates generados por este documento revelaron muchos detalles importantes. El documento se actualiza varias veces después de la discusión, y sirvió como una fuente confiable de información.

49

Informes de experiencia

Otro documento era particularmente importante: el documento de estrategia de migración. En primer lugar, reveló la dependencia entre la migración de los diferentes subsistemas - los subsistemas que había que emigraron antes que otros y así sucesivamente. En segundo lugar, el papel de la migración demostró que había un compromiso entre la calidad del nuevo modelo de datos y la complejidad del proceso de migración: cuanto mejor sea el nuevo modelo de datos era, cuanto más complejo es el mapeo de viejo a nuevo se convertiría. Por otro lado, cuanto más simple se mantuvo la migración, los más fl AWS se llevaría a partir del modelo de datos antigua a la nueva. El cliente aprecia esta discusión mucho.

necesario. En primer lugar, esto incluía un concepto de uso. Los usuarios marco tenían que aprender a incorporar el marco en sus aplicaciones: mientras trabajaban en diferentes sitios, la documentación era indispensable. En segundo lugar, la documentación marco incluye un concepto de diseño que se necesitaba para el futuro mantenimiento y refactorización (véase la página 50).

Estos informes de la experiencia demuestran claramente que los proyectos tenían INDIVIDUAL DOCUMENTACIÓN REQUISITOS.

Algunos proyectos fueron multa con un mínimo de documentación, mientras que otros han

estado en serios problemas sin la documentación más completa. La idea clave de la documentación ágil es no ir sin la documentación 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 quién va destinado.

A pesar de los requisitos de documentación varían, hay varias cosas que, en mi experiencia, todos los proyectos exitosos tienen en común, en lo que se refiere a la documentación. Al revisar los proyectos Para averiguar en qué tipo de documentación que funcionó y lo que no, me di cuenta de algunas cosas una y otra vez. La necesidad de una

En primer lugar, ningún proyecto puede prescindir de una memoria descriptiva y proyectos ágiles no son una

especificación

excepción. Casi todos los proyectos de desarrollo Miré a los documentos producidos especi fi cación, 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 especificación (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 más bien corto, algunos eran más detallada. En la mayoría de los casos, una menos detallada especificación había ninguna desventaja, debido a que muchos detalles especí fi cación única evolucionado con el tiempo. Proyectos de Paracelso y AirView demuestran que es más crucial para el éxito a lo que se refiere

50

Encontrar los temas correctos

Proyecto persistor: documentar un marco Documentación 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 documentación en márgenes razonables, sobre todo con el éxito, aunque también con algunos problemas.

Después del saque inicial del proyecto, el equipo produjo una especi fi cación inicial del marco de capa de acceso a datos. La especificación fue bastante corta, obtuvo la aprobación del cliente, y se utilizó como base para el diseño. 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. Después de un tiempo esto llevó a conflictivas puntos de vista sobre las funciones adicionales tuvieron que ser implementado y que habían sido disminuido. En este punto, la relación entre el cliente, los desarrolladores de marco y de los otros proyectos se hizo bastante tensa. El principal problema no era que había con fl puntos de vista contradictorios, pero que el conflicto no se ha resuelto de manera adecuada cuando había surgido primera fi. Todas las partes consideraron que la especificación de los requisitos adicionales por escrito, habría 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 más importante que enfrenta el proyecto era cómo entrenar a los otros equipos para integrar el marco en sus aplicaciones. Como participaron equipos de diferentes ciudades, comunicación cara a cara sola era insu fi ciente. El equipo decidió usar una mezcla de documentación y talleres. Un concepto de uso para el marco se pasó a todos los demás equipos. Este documento explica cómo el marco podría ser con fi gurada para su uso por una aplicación concreta, la forma en que se podría llamar sus métodos de interfaz, y las directrices generales que deben seguirse. Una vez que los equipos se habían familiarizado con las ideas detrás del marco y las pautas de uso, el equipo corrió marco de talleres en los que se explican en detalle cómo adaptar el marco a las necesidades del proyecto individual. Estos talleres se llevaron de varios días a varias semanas, complementando el entendimiento de que el concepto de uso había suministrado.

Aunque las pruebas jugó un papel muy importante, el equipo, junto con el cliente, decidió que la documentación de los casos de prueba era innecesaria. En su lugar, el equipo puso en marcha un gran número de casos de prueba, y se extendió y se mantiene el código de prueba como el proyecto avanzaba. A medida que las pruebas fueron ejecutable, que sirvieron al proyecto mucho mejor que cualquier documento de prueba podría haber hecho.

51

Informes de experiencia

Navegador de proyectos: confusión debido a la falta de especi fi cación

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 tenía que ser rápido y ligero documentos eran una necesidad. El equipo del proyecto y el cliente habían acordado los siguientes documentos para cada componente de interfaz de usuario: una breve especificación que describe la apariencia y el comportamiento, un documento de diseño que consiste en un diagrama UML y una descripción de la interfaz, y un documento sobre los casos de prueba.

Tenía que haber un acuerdo sobre la especificación, no sólo entre el equipo y el cliente, sino también con el cliente del cliente - el fabricante de automóviles que en última instancia comprar el sistema de navegación. Por desgracia, el cliente final era siempre tarde en comprometerse con un determinado interfaz gráfica de usuario específico de cationes, pero instó al equipo para comenzar con el diseño y la implementación, sin embargo. En algún momento, se pidió al equipo para comenzar la codificación, aunque las especificaciones de componentes no estaban disponibles. Código fue escrito - pero más tarde tuvo que ser reescrito por completo.

En retrospectiva, el equipo consideró que el proyecto tendría pro fi ciado si no hubiera intentado hacer sin especificación escrita. Un documento de especificación podría tener clari ed fi qué partes de la memoria descriptiva se resolvieron y que todavía estaban abiertas. El diseño e implementación podrían se han centrado en aquellas partes que eran claras, dejando espacio para que los cambios en los puntos calientes. Sin ningún tipo de especificación, el equipo consideró que no estaban recibiendo ni de lejos el resultado deseado, y la moral era baja.

De lo contrario, la documentación de peso ligero funcionó bien. Los documentos de diseño y los documentos de prueba consistía en sólo unas pocas páginas cada uno, pero no contenían toda la información necesaria para el cliente para integrar los componentes.

el ESPECIFICACIONES como un esfuerzo conjunto que para completar la especificación hasta el más mínimo detalle. En otras palabras, un incompleto especificación puede ser fi no, siempre está claro que es incompleta, y siempre está claro qué partes están aún por decidir.

En algunos casos, sin embargo, un proyecto no tenía una especificación en absoluto. En una etapa Navegador de proyectos sufrió este destino. Sin escrita especificación estaba disponible hasta bien entrado el proyecto: algunas declaraciones informales eran todo el equipo podría confiar cuando se les pidió que comience la codificación. Al final, tanto código tenía que ser borrado y reescrito. Como consecuencia, la moral entre el equipo fue baja.

52

Encontrar los temas correctos

Proyecto persistor hizo producir una especificación, 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 especificación se convirtió en una molestia cada vez mayor. Un mejor mantenimiento de la especificación habría hecho las cosas más fáciles para todas las partes involucradas.

visiones generales

Una segunda observación que he hecho es que ningún proyecto puede ir sin EL PANORAMA. Cualquiera que sea el nivel de detalle necesario para la documentación de su proyecto, siempre se necesita una visión 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 múltiples capas marco de capa de aplicación

53

Informes de experiencia

Proyecto persistor ofrece un buen ejemplo. En este proyecto, el equipo produjo una especificación, un concepto de diseño, 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 información que ha recibido mayor atención fue 'cuadro grande' del sistema que se presentó en el documento de diseño. 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 también 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 organización, 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 habría 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 través de la documentación 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 sabía exactamente lo que existían relaciones entre los sistemas. Incluso era difícil de obtener una lista completa de todos los sistemas implicados. Una visión general fue mucho de menos. Uno de los principales resultados de este proyecto fue el diagrama general de la aplicación 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 discusión. Se puso el cliente 'enganchados' inmediatamente. Muchas personas lo miraron, hicieron adiciones y correcciones, y así siempre una gran cantidad de información valiosa. El diagrama se actualiza varias veces durante el proyecto con cada paso hacia adelante el análisis del sistema de hecho.

Un documento completamente diferente se dedicó a los riesgos tecnológicos que el proyecto había identi fi cado. Los riesgos fueron juzgados con respecto a su relevancia, así como su probabilidad.

Proyecto Webber (véase la página 56) es otro ejemplo de la importancia EL GRAN IMAGEN puede ser. El objetivo de este proyecto era bastante pequeño para configurar un sitio Web, y el cliente fue mucho más que ver con el diseño del mapa del sitio.

54

Encontrar los temas correctos

Cliente

Clientes comisiones

RES Clientes

replicación Los clientes de VITA

Ventas

Puntos de venta

RES (seguro de propiedad)

VITA (seguros de vida)

Clientes

contratos

contratos

Pago

Control de acceso

LDAP

Administración

Pago

de cuentas

Banco Estadística

actualizaciones

Pago

Teneduría de libros

Seguro de vida

Automóvil Controlador

Recursos humanos

Clientes

Figura 7. Vista Proyecto: el entorno de las aplicaciones

55

Informes de experiencia

Como consecuencia, el diagrama que dio una visión general del mapa del sitio se convirtió en el documento más importante (Figura 8).

Proyecto OpenDoors muestra los problemas que surgen de no tener un documento 'gran cuadro'. En este proyecto, el equipo produjo documentación bastante completa en el portal se desarrollaron, algunos de los cuales era útil y algunos de los cuales no lo era. Como no había ningún documento que describe la arquitectura general del portal, la obtención de una visión general era difícil, y vistas inconsistentes de la arquitectura general emergió.

OpenDoors proyecto: comunicar el diseño Como este proyecto consistió en varios equipos, un cierto grado de documentación era necesaria para gestionar la comunicación entre estos equipos. Sin embargo, poca documentación fue producido para la especi fi cación del portal web. La razón fue que la especificación se realiza cuando el equipo todavía era pequeño, y que las personas, tanto de la compañía de software y el cliente estuviera en ese equipo.

Cuando se trataba de la ejecución del diseño, sin embargo, más personas estaban involucrados y la documentación del diseño se hizo necesaria. Por desgracia, esto dio lugar a una serie de superposición de los documentos de diseño, que, al menos en algunos lugares, ofrecen con fl puntos de vista contradictorios. La documentación del proyecto era bastante confusa en este punto. Los equipos individuales habían proporcionado documentos de diseño que describen los subsistemas individuales, pero no había ninguna descripción de la arquitectura global que mantenga todas las partes juntas. Por otra parte, los documentos de diseño incluyen una serie de detalles que pronto será obsoleto debido a los requisitos cambiantes. La documentación refleja el diseño real. Los diseños individuales de los subsistemas se habían ido por caminos separados, y después de un tiempo se convirtió en difícil de integrarlas en una arquitectura común. En ese momento el proyecto decidió consolidar la arquitectura. Esto fue acompañado por escrito un documento de arquitectura que explicó cómo los diferentes subsistemas fueron a colaborar para formar un portal web. En este documento se hace referencia a algunos de los documentos de diseño anteriores para más detalles, pero pro fi ciado mucho del hecho de que podría prescindir de rápido cambio en sí detalles.

Estos ejemplos muestran que no sólo los grandes documentos de imagen son importantes, también demuestran por qué grandes documentos de imagen son tan importantes. documentos y fotos grandes suelen construir un puente entre la documentación escrita y la comunicación cara a cara. Atraen la atención de los lectores y los invitan a preguntar a los miembros del equipo para obtener información más detallada.

56

Encontrar los temas correctos

página de inicio

Grupos

comités

regionales

Presidentes y Vicepresidentes

Tablero

Noreste (Berlín)

publicaciones

Eventos

revistas

Norte

Actas de

(Hamburgo)

congresos

Grupos de Interés

West

Profesional

Especial (SIG)

(Bonn)

Servicios

reuniones

conferencias

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 pequeña sesión de trabajo para analizar el contenido y la estructura del sitio Web. Resultó que el mapa del sitio se suponía que era un reflejo de la estructura jerárquica de la organización del cliente. Como resultado, el equipo proporciona un diagrama que dio una visión general de la estructura prevista (Figura 8). Este diagrama se convirtió en la parte central de la especificación. Este detalles ignorados intencionalmente tales como el diseño de las páginas web individuales o la lista completa de los hipervínculos que debían incluirse, ya que estos detalles se cambian con frecuencia. Además, sólo de reflexión pequeña fue producido que describe cómo con fi gura el servidor web y la forma de integrar el contenido en el sitio Web.

El diagrama servido bien a su propósito. Fue utilizado a lo largo de varias discusiones. Después de que el proyecto de consultoría terminado el cliente sigue utilizando este diagrama para el desarrollo de su sitio Web.

57

Informes de experiencia

Proyectos persistor, Vista y Webber dan una poderosa evidencia de que la documentación escrita y la comunicación cara a cara no se oponen entre sí. El mismo fenómeno se puede observar en otros proyectos también. Credibilidad

Mi tercera observación es que la SEPARACIÓN DE descripción y evaluación 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 separación entre los requisitos y la recomendación real de una herramienta. Ambos proyectos ganaron credibilidad de esta manera.

Proyecto Contentis: requisitos y recomendaciones El equipo comenzó con un análisis de cómo el cliente desea utilizar un sistema de gestión de contenidos. El equipo se entrevistó con el cliente, el cliente respondió, el equipo inmovilizados lo que habían entendido, y el cliente revisado lo que estaba escrito. Lo que surgió fue una fi cientemente comprensión exacta de los procesos futuros. A partir de esta comprensión del equipo deriva una lista de requisitos para el sistema de gestión de contenidos.

A continuación, el equipo en contacto con varios vendedores y les pidió que ejecutar talleres en los que deben demostrar cómo funcionaban sus sistemas. Se les dio el documento de requisitos para que pudieran prepararse para los talleres. También se les dio una descripción de un caso de uso concreto - el boletín web el cliente quería implementar. En los talleres los vendedores demostraron cómo el boletín podría 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 evaluación que refleja cómo el equipo sintió los diferentes productos en el mercado coincide con los requisitos. El equipo proporciona tanto: un documento de requisitos, claramente objetiva, a raíz de un análisis exhaustivo, y un documento de evaluación, influida por las impresiones de los talleres. Estaba claro que la recomendación formulada en el documento de evaluación incluyó puntos de vista personales. En última instancia, fue el cliente que deciden qué sistema que iban a utilizar.

la preservación de

Por último, me gustaría subrayar una vez más la importancia de mantener una ENFOQUE EN EL LARGO PLAZO PERTINENCIA.

la

Durante la revisión de muchos proyectos me di cuenta de la importancia de los documentos que describen las

Conocimiento

cosas que importan en el largo plazo, especialmente la FUNDAMENTOS DE DISEÑO. Dos proyectos demuestran esta importancia particularmente bien.

58

Encontrar los temas correctos

En el caso del Proyecto persistor, la FUNDAMENTOS DE DISEÑO fue exactamente lo que faltaba en el concepto de diseño. La consecuencia fue que el concepto de diseño resultó ser menos útil como podría haber sido, y el equipo experimentó problemas significativa durante el mantenimiento de la estructura que se podría haber evitado. Proyecto Flexicar tuvo más éxito en la captura de la FUNDAMENTOS DE DISEÑO. El documento de diseño se indica por qué el diseño particular había sido elegido, llamado los pros y los contras de varias alternativas de diseño, y se utiliza ejemplos reales para explicar estas decisiones. Esta era una condición 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 años después del lanzamiento de la primera capa del marco de acceso a datos, la aplicación 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. Sólo unas pocas personas del equipo original eran todavía en el proyecto, y que no estaban familiarizados con los pros y los contras de las distintas alternativas de diseño que el equipo había evaluados dos años antes.

Este fue el momento en que se consultó al concepto de diseño. Por desgracia, se dio poca información sobre la motivación detrás del diseño actual. Se describía los principios del diseño que había sido elegido, pero no mencionó las razones, ni por qué se ha rechazado ninguna diseños alternativos. Un buen grado de ingeniería inversa hizo necesario trabajar en lo que existían alternativas y cuáles fueron las diversas ventajas y desventajas. Había la razón de ser del diseño original ha documentado, el equipo habría sido capaz de reaccionar a las nuevas exigencias mucho más rápidamente.

Flexicar proyecto: la gestión de la responsabilidad del diseño El arquitecto principal había producido un documento de diseño que, a lo largo de los años, 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 también explica la motivación de las decisiones de diseño. Por ejemplo, explica el documento por qué se utilizó un servidor de aplicaciones y por qué persistencia manejada por el frijol se había dado preferencia sobre la persistencia gestionada por contenedor con los (Enterprise Java Beans) EJB, y así sucesivamente.

Informes de experiencia

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 habían estado en el proyecto, por lo que ya se sabía mucho sobre la arquitectura, a pesar de que no se habían inventado. El documento de diseño, sin embargo, les permitió comprender la motivación detrás de las decisiones de diseño que haya uno o dos años antes. El hecho de que un documento de este tipo de diseño estaba disponible hace que sea más fácil para ellos aceptar la responsabilidad del mantenimiento del sistema y las posibles ampliaciones futuras.

59

2

estructuración individual Documentos

voluminosa documentación es parte del problema, no parte de la solución. 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 sabía que tenía el documento correcto? Es probable que tenga - este problema es bastante común.

En la mayoría de los casos, la documentación voluminosa no es exactamente un servicio a los lectores. A pesar de la intención de ofrecer a los lectores una información completa, voluminosa documentación 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 información que están buscando.

En algún momento se dan por vencidos. Frustrado con ir a través de un documento una y otra vez, recurren a otras formas de obtener la misma información, 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 propósito. Ese documento es una pérdida 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 pequeño experimento. Me gustaría preguntarle a mirar en los extractos de los documentos del proyecto indicados en la figura 9 y la figura 10, para ver cuál prefiere.

62

La estructuración de los documentos individuales

Los procesos de implementación 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 redacción son hechas por los editores y son desplegados en caliente a la web. Los cambios estructurales influyen en la programación de los contenidos, tales como código Java dentro de JSP, y se someten a pruebas antes de su lanzamiento.

contenido web se almacena y se editó en un sistema de gestión de contenidos (CMS). A continuación, se explica con más detalle cómo los dos procesos de implementación de la CMS a la web parecen. Para hacer cambios en la redacción, 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 función 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 programación JSP dentro de las plantillas utilizadas en el CMS. Una vez que estos cambios son fi nalizado, el programador llama a una función que exporta el contenido del CMS en una estructura fi sistema le conoce como el área de transferencia. A continuación, 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 máquina de prueba. Programación 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 máquina 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 información. Su apariencia y estructura no podrían ser más diferentes, sin embargo. El primer extracto consiste en unos pocos párrafos, mientras que la segunda cuenta con elementos estructurales más fuertes y un diagrama para la ilustración. Curiosamente, el segundo fragmento es más largo que el primer uno. Pero no es tan densa, y debido a su estructura mejorada tiene menos de una sensación voluminosa.

63

Los procesos de implementación 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 redacción son hechas por los editores y son desplegados en caliente a la web. Los cambios estructurales influyen en la programación de los contenidos, tales como código Java dentro de JSP, y se someten a pruebas antes de su lanzamiento.

El siguiente diagrama explica que los sistemas están implicados.

Desplegar

Exportación

CMS

Desplegar

Servidor web

Transferir

Transferir Área de

servidor de prueba

cambios de redacción

1. Un editor añade o contenido cambios en el sistema de gestión de contenidos (CMS).

2. Un editor en jefe opiniones y publica el contenido. Al llamar a una función 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 programación JSP dentro de las plantillas utilizadas en el CMS.

2. Una vez que los cambios son fi nalizado, el programador llama a una función que exporta el contenido del CMS en una estructura de cadena de música 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 máquina 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 máquina 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 estructuración de los documentos individuales

Los lectores pueden acceder a la información mucho más rápido en los documentos que siguen el estilo del segundo fragmento, que se toma de OpenDoors proyecto. documentación ágil sigue este enfoque y su objetivo es producir mejores documentos a través de las siguientes técnicas:

•

La idea clave es proporcionar documentos con una estructura útil que guía a los lectores a través del material, lo que ayuda a obtener la información que necesitan.

•

La inclusión de diagramas significativos puede hacer que los documentos un disparador para la comunicación cara a cara.

•

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

Este capítulo comienza con patrones que toman un vistazo general a la estructura de los documentos, luego pasa a los patrones que sugieren elementos de hormigón se pueden utilizar. La Figura 11 proporciona una visión general.

Estos patrones no sólo para hacer más accesibles los documentos a sus lectores, sino que también ayudan autores escriben los documentos de proyectos con mayor rapidez. Agregar información a un documento bien estructurado es mucho más fácil que la actualización de un artefacto literario complejo. Una estructura de documento útil allana el camino para documentos ligeros ya un proceso de documentación á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 gustaría que lo remita al cuerpo de la literatura. lectores de habla inglesa se hallar Los elementos del estilo por William Strunk y EB White más útil - corto, preciso y al punto (Strunk Blanco 1979). lectores alemanes podrían bene fi cio de los libros de Wolf Schneider (Schneider 1996, 1999). Por último, me gustaría señalar que los patrones en este capítulo 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 cómo puede mejorar sus documentos mediante la mejora de su estructura y al hacerlos más accesibles a sus lectores.

sesenta y cinco

ESQUEMAS

AMBIGÜEDADES

MESAS

juiciosa

a menudo incluye puede usar

a menudo incluye

GUIAS PARA

La información estructurada

incluye

LECTORES

señalarle

pueden incluir Thumbnail Sketches

el

utiliza a menudo

GLOSARIO

puede usar

incluye

Referencias trazable

introducir

Referirse a

HISTORIA DEL DOCUMENTO

Figura 11. Los patrones para la estructuración de documentos individuales

66

La estructuración de los documentos individuales

La información estructurada Problema

¿Cómo puede la información sea presentada de una manera fácilmente 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 búsqueda de información y que lee los pasajes más largos sólo cuando sea necesario. Idealmente, los documentos del proyecto deben permitir tanto para la lectura secuencial y para la recuperación de información rápida, por lo que sirve ambos tipos de lectores.

Robert Horn analizó la comunicación escrita y encontró que los seres humanos pueden procesar información estructurada más rápida y más fiable que la información no estructurada (Horn 1989). Los lectores pueden recuperar información 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 información específica, están dispuestos a navegar a través de un documento por un tiempo, pero renunciar cuando su búsqueda resulta infructuosa y asumir que la información no está disponible.

Esto podría sugerir que los documentos del proyecto deben organizarse como hipertexto, el uso de hipervínculos para llevar a los lectores a través de las partes de un documento que son relevantes para ellos. Sin embargo, hay que tener en cuenta que los documentos deben también permiten la lectura secuencial, y que el hipertexto es contrario a la intuición 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 psicológico prominente nos da una pista. En 1956, el psicólogo George A. Miller observó que las personas son generalmente capaces de identificar y memorizar unos siete piezas de información a la vez (Miller 1956). Esta observación se puede aplicar a la estructura general de los documentos. 4 Por ejemplo, un capítulo que consiste en significativamente más de siete secciones es difícil de manejar para los lectores ocasionales que buscan para memorizar la estructura del documento. Por otro lado, un capítulo 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 página 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.

67

La información estructurada

Recuadro: el número mágico siete papel pionero de George A. Miller de 1956, ' El número mágico siete, más o menos dos: Algunos límites en nuestra

capacidad de procesamiento de la información '(Miller 1956), ha sido muy referenciado en la literatura sobre ambas ciencias de la comunicación y la informática. 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 estímulos en forma lineal, que es unidimensional, orden tal como puntos en una línea, campos o loudnesses. La gente tenía que identificar un estímulo elegido al azar.

La relación de pruebas con éxito frente al número total de pruebas se hace más pequeño como el conjunto de estímulos se hace más grande. Miller observó que alrededor de un total de siete estímulos, las posibilidades de precisa fregadero catión identi fi dramáticamente. Esta observación era independiente del tipo de estímulo - visual, acústica o de otro tipo.

Miller concluye que siete representa un límite superior en la capacidad humana para el procesamiento de información, y en las reivindicaciones del número siete que hay 'algún patrón que rige su apariencia'.

Es importante entender que este límite de siete años se aplica:

•

Cuando los estímulos están en orden lineal, y

•

Cuando los estímulos individuales necesitan ser identificados fi

La regla de Miller, por tanto, no dice que una novela no debe tener más de siete capítulos. Es cierto que los capítulos de una novela son, en orden lineal, pero ¿por qué querría alguien para identificar un capítulo 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 más de siete páginas. Los usuarios pueden tener para identificar una página individual de un sitio completo con el fin de recuperar alguna información en particular. Pero entonces, los sitios Web no están organizados de una manera unidimensional.

La regla de Miller se aplica a los documentos típicos de proyectos de software. Debido a que tales documentos se estructuran en capítulos, secciones, etc., que están 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 información en otro lugar. lectores ocasionales pueden familiarizarse con un documento mucho más fácilmente si la estructura del documento - sus capítulos y secciones - Cumple 'Regla de los Siete' de Miller.

68

La estructuración de los documentos individuales

número de capítulos en todo el documento y el número de los incisos a una sección.

Sin embargo, la regla de siete no dice nada acerca de cómo la información debe ser profundamente estructurado. Capítulos, secciones y subsecciones son bastante normal, pero ¿qué pasa con los sub-subsecciones? No hay un límite general a la profundidad de los documentos estructurados, pero parece que la mayoría de los lectores prefieren documentos que se estructuran hay más de tres niveles de profundidad.

Solución

La mayoría de los documentos del proyecto están mejor organizados como texto secuencial sin embargo, bien estructurado. Esto comienza con los capítulos y secciones bien elegidos, pero también puede extenderse a la utilización de bloques de construcción 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 capítulos significativos, secciones y subsecciones tal vez. Dada esta estructura, los lectores pueden acceder a la información en un documento mucho más fácilmente que si la estructura no estaba. La estructura es más eficaz si se sigue la regla de siete años de Miller: unos siete capítulos a un documento, unos siete secciones para un capítulo y así sucesivamente.

•

Puede mejorar la estructura de los documentos mediante la adopción de un segundo paso. La Figura 12 ilustra una página que podría ser tomada de un documento de diseño - una sección que consta de cinco bloques de construcción. ¿Qué podrían representar estos bloques de construcción? Por el bien del argumento, vamos a suponer que la página se describe una clase, y que los bloques de construcción representan el nombre de clase, un texto introductorio, un diagrama de clases, una interfaz específica fi cación y un gráfico de secuencias de mensajes. A continuación, puede utilizar las secciones que están estructurados de esta manera repetida en todo el documento, que describe todas las clases de forma coherente. Una estructura consistente para una descripción de la clase es, por supuesto, sólo un ejemplo, pero una estructura similar podría ser igualmente útil en muchos otros tipos de documentos.

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

Discusión

Para un ejemplo rápido, mirar hacia atrás a la Figura 9 y la Figura 10. Figura 10 presenta la información estructurada, la Figura 9 no lo hace. La estructura es exactamente lo que hace

69

La información estructurada

Figura 12. La información estructurada - una sección que consta de cinco bloques de construcción

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 información estructurada es tarjetas CRC (Beck Cunningham 1989). Tarjetas CRC proporcionan una estructura común para describir las responsabilidades de las clases involucradas en un diseño. La estructura coherente de las tarjetas CRC hace tarjetas CRC rápidas a seguir y convenientes para trabajar con ellos. La forma de patrón utilizado en este libro es otro ejemplo de información estructurada. Cada patrón consta de cinco componentes básicos: el título, el problema, las fuerzas, la solución y la discusión. La estructura hace que sea fácil para los lectores para identificar qué parte del patrón se mantiene el tipo de información. Etiquetas como problema, fuerzas, solución y discusión representar a la meta-información que usted, el lector permite, para clasificar la información que este libro tiene reservado para usted.

70

La estructuración de los documentos individuales

Una idea importante detrás de la estructuración de la información es que el uso de diagramas y tablas puede hacer que la estructura de un documento más visible. Esta visibilidad ayuda a los lectores perciben el contenido de un documento. La figura 12 ilustra esto con dos bloques de construcción que consiste en un diagrama, y ​la figura 10 da un ejemplo concreto. En general, ESQUEMAS juiciosa puede proporcionar excelentes vistas generales, mientras TABLAS inequívoca información sistemática presente. Además, puede mejorar la estructura de los documentos por medio del diseño y la tipografía, especialmente con El uso cuidadoso de variaciones de tipo

y mediante FALLO Y CUIDADO SOMBREADO.

Todas estas ideas acerca de la estructuración de documentos plantean la cuestión 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, asegúrese de incluir DIRECTRICES PARA LOS LECTORES

y una HISTORIA DEL DOCUMENTO. A menudo se necesita un GLOSARIO, así

como una sección con Referencias trazable a otros documentos. Cuando se trata de más fi estructuración de grano fino, Thumbnail Sketches añadido a las secciones del documento da un acceso más rápido a los lectores ocasionales. Un final Observación sobre la regla de siete. Al estructurar un documento, siempre se debe mantener el principio general de la presentación La información centrada en el fondo de su mente. No hay ningún punto en la creación de siete capítulos, si usted no tiene suficiente material para siete capítulos. La creación de un capítulo o una sección es sensato sólo cuando se puede de fi nir su enfoque. Así que toma la regla de siete años con un grano de sal. 5

Diagramas juiciosas Problema

¿Cómo pueden los autores proporcionar una visión general de las estructuras y procesos de una manera conveniente?

Efectivo

Estructuras y procesos juegan un papel importante en la ingeniería de software. La estructura de un sistema de software describe cómo se organiza el sistema y la forma en que se compone de partes más pequeñas. Procesos describen el aspecto dinámico del software - la interacción y el comportamiento impulsado por el Estado, entre otras cosas.

5. Por ejemplo, el número de capítulos en este libro es en el extremo inferior de la gama que la regla de siete sugiere, mientras que el número de patrones en cada capítulo tiende a estar en (o incluso un poco más allá) del extremo superior.

71

Diagramas juiciosas

Si nos fijamos en las técnicas 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 más que mil palabras. Diagramas hablan a nuestra intuición. También existe evidencia científica c fi que los diagramas de los lectores perciben ayuda información. Por ejemplo, los libros de Edward Tufte en la representación visual de la información dan una cuenta impresionante (Tufte 1997, 2001). Por otra parte, hay una razón psicológica sutil qué diagramas veces son más adecuados para explicar el material para los lectores. Diagramas nos permiten ilustrar información de una manera de dos dimensiones, lo que aumenta su comprensibilidad (Miller 1956).

Hay más puntos a favor de los diagramas. Los lectores tienden a aburrirse con monótonas, textos largos. Textos que incluyen diagramas son mucho menos monótono. Diagramas sirven como llamativos que atraen a los lectores de forma rápida, y también ayudan a los lectores a memorizar información. Los lectores suelen asociar un texto con los diagramas incluidos, de manera que cuando navegan por el texto en busca de información específico de un tiempo más tarde, los diagramas les dan orientación (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 información completa, pero a menudo dejan sin contestar preguntas detalladas.

Solución

Los diagramas pueden proporcionar excelentes vistas generales, mientras que un texto que la acompaña 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 estructuración de los documentos individuales

Hay una amplia gama de cosas que se pueden describir muy bien a través 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 visión general de arquitectura

•

Los diagramas de clases

•

Los diagramas de interacción

•

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 información que se expresa mejor visualmente. Los mejores diagramas son a menudo los que son clara y sencilla. Idealmente, un diagrama utiliza sólo un número bastante reducido de elementos gráficos, lo cual, si es necesario, deben explicarse en una leyenda. A veces, incluso un dibujo pizarra perfectamente estructurado capturada por una cámara digital hace un diagrama excelente (Cockburn 2001, Ambler 2002).

Discusión

Los diagramas son prominentes en una buena documentación de todas formas, pero son particularmente importantes en un contexto ágil. documentación Agile da preferencia a comunicar EL PANORAMA anotando más de una larga lista de detalles, por lo que un diagrama que suele ser el método de elección. Los diagramas pueden tener una idea de ancho, diagramas pueden conseguir comenzaron una discusión, diagramas de promover la comunicación. Debido a que los diagramas son tan buenos llamativos, pueden aumentar la e fi ciencia de ESTRUCTURADO INFORMACIÓN. Si decide organizar su documento con la ayuda de una estructura distinta, la inclusión 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 visión general y para

explicar cómo las secciones de un documento se relacionan entre sí. En una vena similar, pero en una escala más grande, documento introductorio de un proyecto puede utilizar un diagrama para dar una visión general de toda la documentación y para explicar cómo los documentos individuales se relacionan entre sí. En otras palabras, un diagrama puede visualizar la Documento horizontal.

73

Tablas sin ambigüedades

Figura 13. Mezcla de texto con un diagrama

Tablas sin ambigüedades Problema

¿Cómo pueden autores presentan información sistemática de una manera precisa?

Efectivo

información sistemática es común en los proyectos de software. En un mundo donde el pensamiento analítico juega un papel importante, la información sistemática se convierte en una herramienta esencial de la operación.

Piense en todas las listas que cumplir: la lista de todos los módulos de un sistema, de todos los métodos de interfaz, de todos los códigos de error, de todos los tipos de datos, de todos los paquetes de trabajo, sólo para nombrar unos pocos. Más ejemplos de información sistemática también se encuentran en muchos proyectos: esquemas de clasi fi cación, pasos de un proceso, las asignaciones y así sucesivamente. Dicha información sistemática es a menudo objeto de documentación. Los miembros del equipo, sin embargo, no están interesados ​en la lectura de un texto largo, cuando todo lo que quieren saber fácilmente se podría presentar como una entrada de la lista.

El uso de tablas para presentar información sistemática es la opción obvia. Las tablas son claras y directas. Similares a los diagramas, tablas pro fi ciarse de la ventaja psicológica que son de dos dimensiones. Las dos dimensiones están representadas por las filas y columnas, que permiten que los arreglos de texto secuencial no puede procesar.

74

La estructuración de los documentos individuales

De manera similar a los diagramas, tablas pueden hacer un texto menos monótona. Aunque sólo sea por la variedad tipográfica, las tablas pueden atraer la atención del lector con facilidad. Sin embargo, las tablas también tienen la desventaja de que comparten con los diagramas. Tablas sólo ofrecen poca expresividad lingüística. Si el material requiere un argumento para su explicación, más que puede caber en una celda de tabla, una tabla por sí sola no puede ser suficiente.

Solución

Mesas ofrecen un formato compacto para la presentación concisa e inequívoca de la información. La siguiente lista no pretende exhaustividad, pero le da algunos ejemplos de materiales sistemáticas que muy bien pueden ser presentados en las tablas:

•

Especí fi caciones de interfaz (nombre de la función, la firma, abstracto, códigos de error)

•

Las listas de clases, métodos, tipos de datos, etc.

•

tablas de gestión de errores (código de error, la reacción)

•

La comparación de los pros y los contras de una opción de diseño

•

Diferentes medidas que deben tomarse en un proceso o una actividad

•

Paquetes de trabajo y sus plazos

Cuanto más autónomo de una mesa es, más fácil es de comprender. Idealmente, los encabezados de las filas y columnas dan los lectores toda la información necesaria para entender la tabla. Información de fondo sobre lo que se presenta en la tabla a menudo tienen que entrar en el texto que lo rodea, sin embargo.

Discusión

Las tablas se encuentran a menudo en el contexto de La información estructurada, ya que añadir a la estructura del documento. La figura 14 ilustra esto. Las tablas pueden ser utilizados para implementar el SEPARACIÓN DE descripción y evaluación,

por ejemplo, dedicar una columna a otra y observaciones a los comentarios, o

mediante la colocación de los hechos en una mesa y interpr etations en el texto que lo rodea.

La variedad en el diseño ha sido mencionado como una de las ventajas que ofrecen las tablas. FALLO DE CUIDADO y sombreado

tipográfico.

le permite generar tablas que se ven bien desde un punto de vista

75

Directrices para los lectores

Figura 14. Una tabla claramente estructurado entre texto circundante

Directrices para los lectores Problema

¿Cómo 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 típicamente ocupando diferentes roles que tienen diferentes necesidades de información. 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 visión general del tema, otros podrían estar buscando algún detalle específico, mientras que un tercer grupo podría querer leer el documento en su totalidad.

Además, algunos documentos requieren que los lectores han leído otros documentos previamente, o de otra manera estar familiarizados con ciertos materiales. por lo tanto, deben estar informados de los requisitos previos para la comprensión de un documento de lectores potenciales.

También puede haber dependencias dentro del propio documento. Los capítulos de algunos documentos son relativamente independientes entre sí, y los lectores pueden concentrarse en los capítulos en los que están interesados. Pero a veces

76

La estructuración de los documentos individuales

los lectores tienen que pasar por un capítulo antes de que sean capaces de comprender al otro.

Solución

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

Las directrices deben evitar que los lectores de estudiar los documentos que no contienen la información que necesitan. También deben evitar que los lectores de pasar por un documento completo cuando sólo partes de él son relevantes. Para ello, las directrices deben responder a las siguientes preguntas:

•

A quién va dirigido el documento?

•

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

•

¿Cómo se organiza el documento?

•

¿Cuáles son las dependencias entre los diferentes capítulos del documento? ¿Hay un orden especí fi co en el que leer los capítulos?

•

¿Cuáles son las relaciones con otros documentos? ¿Hay otros documentos que se espera que los lectores que han leído previamente?

•

¿Cómo pueden los lectores obtener una visión rápida 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 actualización de una versión anterior, qué partes han cambiado?

Discusión

Sin embargo, las directrices para los lectores aparecen en detalle, que están destinados a acoger al lectores de destino

a un documento. Ellos dicen explícitamente que la

OBJETIVO LECTORES juiciosa)

son, frente a ellos, y hacerles saber cómo utilizar el documento. Un diagrama (ver ESQUEMAS

es a menudo el método de elección para la descripción de la organización general de un

documento, así como las dependencias entre sus capítulos. El diagrama puede servir como una hoja de ruta para los lectores cuando navegan a través del documento de encontrar las partes de interés. Señalando a los lectores cómo pueden obtener una visión rápida es particularmente fácil cuando los capítulos individuales del documento se proporcionan con MINIATURA Dibujos. Es también ú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.

77

Thumbnail Sketches

Thumbnail Sketches Problema

¿Cómo pueden los lectores obtener una visión general de los temas tratados en un documento?

Efectivo

Es difícil para los lectores de encontrar lo que buscan en un documento que contiene una gran cantidad de información. Las guías pueden decirle a los lectores lo que puede esperar del documento, pero no pueden decir dónde buscar cualquier detalle específico. Una clara estructura de capítulos, secciones y subsecciones hace que sea más fácil para los lectores de encontrar información en particular, sin embargo, una estructura clara por sí sola no puede ser suficiente para que los lectores puedan recuperar información de forma rápida. recuperación de información rápida es necesaria, sin embargo. Idealmente, los lectores pueden navegar a través de un documento en un nivel alto, y cavar más profundo cada vez que sienten que alguna parte del documento es particularmente relevante para ellos. Gerald Weinberg explica en La psicología de la Programación de Computadoras: '... los diferentes usuarios de la documentación necesitarán diferentes niveles de detalle de la información que extraen. El nivel más alto se debe simplemente su fi cientemente detallada para indicar al usuario si es o no será capaz de leer los documentos '. (Weinberg 1998)

Solución

bocetos en miniatura proporcionan breves descripciones de las secciones de un documento, incluidos los objetivos generales de la sección, así como sus principales ideas.

Un documento que suministra bocetos en miniatura permite la lectura secuencial en diferentes niveles de detalle. Después de leer un esbozo en miniatura, los lectores pueden decidir si les gustaría ir más profundo o si hay que pasar a la siguiente sección.

Hay dos formas de configurar bocetos en miniatura:

•

Usted puede dejar que cada sección comienza con una especie de resumen o sumario.

•

Se puede elegir algunos párrafos de cada sección, aunque no necesariamente al comienzo, y el uso de los bocetos como miniatura. técnicas de diseño se pueden utilizar para su identi fi cación.

Ambas técnicas 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 imágenes en miniatura para una exploración rápida.

78

Discusión

La estructuración de los documentos individuales

Este patrón se basa en la idea de La información estructurada. Cuando se utiliza una estructura común consistente en todo el documento, bocetos en miniatura aparecen repetidamente en el mismo lugar dentro de una sección, donde pueden ser fácilmente 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 patrón coherente. Para cada patrón, la sección de problema y el primer párrafo fi de la sección de solución forman un esbozo en miniatura. Puede hallar la idea principal detrás de cada patrón sin tener que leer todos sus detalles. Las partes en negrita le dan una primera impresión: se puede ir más profundo, pero no tiene que hacerlo.

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

Referencias trazables Problema

¿Cómo pueden ser documentos vinculados el uno al otro?

Efectivo

Cada documento se supone que debe centrarse en un solo tema. Sin embargo, ningún documento puede ser visto de manera aislada. Siempre hay temas relacionados que necesitan ser entendidos de antemano o documentos que proporcionan información 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? Después de todo, el lector se supone que debe buscar esa referencia si se requiere más información. Una referencia a un documento que está disponible no vale mucho y podría también quedar fuera.

Solución

Un documento debe incluir referencias a otros documentos sólo 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 sólo mientras esos documentos pueden ser distribuidos entre el equipo. No debería haber ninguna referencia a los documentos que están restringidos al uso interno o que subyacen a un acuerdo de confidencialidad.

79

Glosario

•

Casi todas las organizaciones tienen bibliotecas que contienen la literatura estándar de la ingeniería de software. Las referencias a dichos libros y revistas son fáciles de seguir.

•

Cientí fi cos publicaciones que no son fácilmente disponibles son un asunto diferente. Las referencias a estas fuentes son a menudo difíciles de rastrear, y son por lo tanto inadecuado.

Dentro de un proyecto, es útil no sólo para hacer referencia a un documento relacionado, sino también para señalar a los lectores de manera explícita en el que puedan hallar el documento.

Discusión

Usted puede preguntar si las referencias se pueden evitar por completo. los La información centrada patrón proporciona la respuesta. Su objetivo debe ser producir documentos independientes que no están 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 inclusión de Thumbnail Sketches

puede representar un buen compromiso. Esta solución evita superposiciones, en gran medida,

aunque no totalmente, sin dejar de añadir a la libre containedness del documento. La adecuación de las referencias también depende de quién 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 también lo han hecho los miembros del equipo en contraposición a los gerentes. Al hacer referencia a otros documentos, es necesario tener esto en cuenta.

Los documentos electrónicos pueden utilizar hipervínculos 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 técnica para los documentos que están destinados para su uso en línea. Sin embargo, muchos documentos de los proyectos están destinados a ser impresa, por lo hipervínculos sólo son de uso limitado. (Véase también la discusión sobre De fácil lectura-MEDIA.)

Glosario Problema

¿Cómo pueden autores asegurarse de que los lectores a comprender el vocabulario utilizado en un documento?

Efectivo

Los términos técnicos a menudo se producen en la documentación producida por un proyecto de software. Los documentos de diseño en particular, no pueden prescindir de términos que son específico a la tecnología utilizada. Mientras que algunos términos técnicos más o menos

80

La estructuración de los documentos individuales

pertenecen al vocabulario estándar de ingeniería de software, los lectores podrían no estar familiarizados con los demás. Por otra parte, muchos proyectos de software utilizan una terminología que es especí fi ca a la organización del cliente o el dominio de aplicación, y no todos los lectores que cabe esperar que estar familiarizado con él. términos de dominio especí fi cas pueden ser un obstáculo, sobre todo a los nuevos miembros del equipo.

Si usted explica todos estos términos 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 más precisa.

Por otra parte, una explicación 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 nición o explicación.

Solución

Un glosario puede explicar términos técnicos, así como los términos especí fi cos para el dominio de aplicación. La mayoría de los documentos del proyecto pueden bene fi ciarse de un glosario. Los documentos más técnicos requerirán principalmente las explicaciones de los términos técnicos, mientras que las especificaciones de requisitos se basan en gran medida en el vocabulario del dominio de aplicación. En un primer paso, la creación de un glosario es fácil:

•

El glosario enumera todos los términos especí fi cos pertinentes al documento en orden alfabético.

•

Cada entrada presenta una definición de fi o explicación que sea entendido por los miembros del equipo, y quizás incluye una referencia a otras fuentes de información.

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.

Discusión

Dar de fi niciones de los términos de dominio especí fi cas puede no ser fácil. Con respecto a ESPECIFICACIONES como un esfuerzo conjunto

ayuda, ya que casi siempre se puede obtener una buena explicación 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.

81

Historia del documento

Un gran proyecto podría considerar una herramienta glosario - esencialmente una pequeña base de datos de términos técnicos y términos del dominio de aplicación - que se puede utilizar para extraer una lista de esos términos que necesita en un contexto especial. Dicha herramienta gestiona redundancia entre los glosarios de varios documentos. Debe, sin embargo, ser elegida sólo si la gestión de la redundancia de forma manual no es más rápido. No hay ningún punto en el uso de una herramienta si la herramienta no hace las cosas más fáciles.

Historia del documento Problema

¿Cómo se puede evitar la confusión 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 también 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 periódicamente pueden perder la sincronización con lo que describen. No se puede actualizar la documentación a la misma velocidad que aquella a la que avanza el programa, de lo contrario se estaría actualizando la documentación sobre una base diaria. La consecuencia es que en entre actualizaciones, documentación 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 podría ser un poco fuera de fecha, y siempre y cuando saben que, mientras tanto, el software puede haber sido desarrollado aún más.

Solución

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 versión. Se extiende como evoluciona el documento. Cada entrada se asocia típicamente con un número de versión para el documento, e incluye la siguiente información:

• •

El autor de esa versión. Una breve lista de los cambios realizados desde la última versión del documento fue puesto en libertad.

•

Si el documento se describe real del software, la versión del software al que se refiere el documento.

82

La estructuración de los documentos individuales

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

Discusión

El mantenimiento de un historial del documento sólo tiene sentido en presencia de CONTINUO DOCUMENTACIÓN. El historial del documento no pretende ser una excusa para que los documentos no están 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 añadir entradas a un historial de documentos de forma automática, aunque normalmente esto es posible sólo con texto sin formato archivos.

Informes de experiencia Veamos cómo se aplicaron los patrones en este capítulo en la documentación de algunos de nuestros proyectos de ejemplo. estructura del

Me gustaría comenzar con la idea de La información estructurada. Esta idea estaba presente en la

documento

documentación de la mayoría de los proyectos, pero algunos documentos demuestran la utilidad de la información estructurada particularmente bien. Volvamos por un momento al experimento al principio de este capítulo. La Figura 10 en la página 63 contiene una página de la descripción de despliegue que OpenDoors proyecto producido. La Figura 9 en la página 62 contiene una página I burlado para demostrar la diferencia. Figura 10 Características La información estructurada, mientras que la Figura 9 no lo hace.

Hay más ejemplos de cómo la adición de estructura hace que un documento sea más legible. El documento de diseño de de fi ne una estructura de texto Navegador de proyectos que se aplica de manera uniforme a la descripción del diseño de todos los componentes. La Figura 15 muestra la descripción de uno de tales componentes. La descripción de cada componente presenta una breve declaración visión general, una descripción de la interfaz, una descripción 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 cómo cada interfaz

83

Informes de experiencia

Caja de navegación El cuadro de navegación 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 pequeña 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 especificación para un ejemplo de pantalla. La clase NavigationBox implementa la interfaz para los controles de interfaz de usuario.

Descripción de interfaces

clase NavigationBox // Este método 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 dirección deseada como un parámetro //. movimiento public void (sin firmar dirección corta); // Este método cambia el nivel de detalle que se muestra. // Dependiendo del parámetro que se pasa al método, // la pantalla ya sea zooms en el mapa en un paso, o // se amplía hacia fuera.

zoom public void (booleano de acercamiento);

Diagrama de clase

> interfaz ControlIfc

NavigationBox movimiento de zoom

EventListener

Figura 15. Navegador de proyectos: información estructurada aplicada a un documento de diseño

84

La estructuración de los documentos individuales

4.2.1 Adición de un objeto

addObject () EN OBJECTTYPE

: DT DE TIPO

EN Fullkey

: DT-KEY

EN EntryDate

: DT-FECHA

EN processNumber

: DT-NR

Condiciones previas: ninguna

Función: La capa de acceso de datos proporciona una versión inicial de un nuevo objeto, de acuerdo con la fecha de entrada y el número de proceso pasado a ella como parámetros. Tras la inicialización, el nuevo objeto todavía puede ser incompleta; componentes se pueden añadir sucesivamente. El estado del nuevo objeto está “pendiente”. La clave que se pasa a esta función como un parámetro de entrada es una clave lógica, que pueden o no llevar información aplicación específica. Normalmente es generado por un módulo específico fi que todas las aplicaciones pueden utilizar. En caso de que la tecla fi cado se ha usado previamente para la adición de un objeto, se devuelve un código de error.

El número de proceso es generado por el sistema de gestión de fl ujo de trabajo. Códigos de retorno:

RC-OK

El objeto se ha introducido y inicializado correctamente.

RC-KEY

La clave lógico especificado no está disponible.

RC-DB

La base de datos no está disponible.

RC-PARAMETROS

La fecha de entrada o el número de proceso son ilegales.

Figura 16. Proyecto persistor: un documento bien estructurado

85

Informes de experiencia

método puede ser aplicado. La Figura 16 muestra la descripción de uno de tales métodos. La descripción de la interfaz se compone de bloques de construcción para la firma, la lista de parámetros, condiciones previas, una descripción y los códigos de error. A lo largo de todas las descripciones de los métodos, la firma, la lista de parámetros y el primer párrafo de la ficha de descripción Thumbnail Sketches para cada función. Los códigos de error para cada función se presentan utilizando TABLAS inequívoca.

elementos

Vamos a echar un vistazo más de cerca el concepto de uso de Proyecto persistor, ya que cuenta con varios

útiles

de los elementos útiles los patrones en este capítulo sugieren que deben incluirse en un documento. La Figura 17 muestra la HISTORIA DEL DOCUMENTO

tomado de una de las primeras páginas 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 autores

Estado de la versión

Fecha

0.1

1999-Jun-19 A. Rüping

borrador

0.2

borrador

1999-Jun-24 A. Rüping

0.3

borrador

1999-Jun-30 A. Rüping

Observación Primer borrador

•

Descripción de la arquitectura

•

utilizando la interfaz

Unos pequeños cambios Los cambios después de la revisión interna:

•

modelo de estado añadió

•

ejemplo en el control de versiones añadido

0.4

borrador

1999-Ago-06 A. Rüping

Unos pequeños cambios: • API de fi niciones

• 1.0

lanzado 1999-Ago-30 A. Rüping

2.0

lanzado 1999-Oct-22 A. Rüping

operaciones lógicas

Los cambios después de la revisión externa

Actualizar reflejando el lanzamiento de la nueva versión del marco

Figura 17. Proyecto persistor: un historial del documento

86

La estructuración de los documentos individuales

La Figura 18 muestra la DIRECTRICES PARA LOS LECTORES, el cual, en el documento original, aparecerá al comienzo de la introducción. Ellos se refieren directamente a los lectores a través de unas palabras introductorias. A pesar de que son bastante cortos, que dejan claro que se debe leer el documento y cómo 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 atención al cliente. Se espera que más proyectos para comenzar pronto; van a utilizar la capa de acceso de datos también. Para permitir que la capa de acceso de datos a utilizar por varios proyectos, se ha diseñado 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 cómo 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 básicos de la capa de acceso de datos utiliza, y luego Describa brevemente su arquitectura. La parte principal de este documento es una descripción de la API que explica cada función por separado. Directrices para el seguimiento de con fi guración. Concluimos con algunas pistas que explican cómo 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 apéndice al final del concepto de uso. Se explica brevemente los términos especiales utilizados en el documento, incluyendo tanto los términos técnicos y especificidad del vocabulario c para el dominio de aplicación.

Finalmente, la Figura 20 muestra la lista de referencias del documento de uso. Son de TRACEABLE REFERENCIAS, como miembros del equipo pueden obtener fácilmente la información

87

Informes de experiencia

Glosario estado

La capa de acceso de datos permite que los objetos estén en diferentes estados: activo, pendientes y inactivo. En el dominio de aplicación de estos estados se ajustan a los modos en los que un contrato de seguro puede ser: válido, en proceso de revisión, que se ofrecen.

transacción

Una transacción lógica consiste en la totalidad de pasos a realizar juntos: un caso de uso

lógica

atómica. Si un paso conduce a un error o se interrumpe, los pasos anteriores deben hacer ser deshecho.

transacción de la

Una transacción de base de datos consiste en una secuencia de escritura / actualizar / borrar los comandos

base de datos

que están bien comprometidos con la base de datos (commit) o ​ignorados (rollback). Este es el mecanismo que ofrece una base de datos para implementar transacciones lógicas. En la capa de acceso de datos, transacción lógica puede constar de varias transacciones de base de datos. La capa de acceso de datos utiliza mecanismos de caché para asegurarse de que una reversión lógica es posible.

Figura 19. Proyecto persistor: un glosario

referencias [* MS] Resumen de gestión, "~ / Arquitectura / summary.doc". [* RS] Requisito especí fi cación, "~ / especificación / requirements.doc". [*ANUNCIO]

Arquitectura y diseño general, "~ / Arquitectura / Arquitectura + design.doc". [GoF]

Erich Gamma, Richard Helm, Ralph Johnson, John Vlissides. “Patrones de Diseño”, Addison-Wesley, 1995.

Figura 20. Proyecto persistor: lista de referencias

88

La estructuración de los documentos individuales

al que se refieren: un par de otros documentos del proyecto y un libro fácilmente disponibles en el diseño 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 través de varios diagramas que resultaron de gran utilidad. EL GRAN IMAGEN documentos descritos en la Figura 6, Figura 7 y Figura 8 (páginas 52-56), hacen uso de ESQUEMAS juiciosa, y lo mismo hizo el concepto de diseño del Navegador de proyectos (Figura 15). Creo que es fácil para que usted pueda imaginar muchos más ejemplos - es probable que haya llegado a través de muchos diagramas útiles en su práctica cotidiana.

Te voy a dar sólo un ejemplo más. 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 través de un diagrama la historia de dos dimensiones es un concepto común en los sistemas de información 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 algorítmica, 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 avión. Debido a que el marco utilizado la historia de dos dimensiones mucho, el concepto de uso incluye varios diagramas que explican el concepto. Después 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 increíblemente abstracto. Pero ahora que he visto estos diagramas, he finalmente entendió. Varios otros miembros del equipo expresaron experiencias similares.

No sólo los diagramas de añadir estructura a un texto y lo hacen menos monótona - lo mismo es cierto para las tablas. Una vez más, estoy seguro de que puede pensar en muchos ejemplos, así que sólo voy a presentar dos aquí.

La Figura 22 muestra un extracto de una tabla que enumera los requisitos colocados en el sistema de gestión de contenido Web en el Proyecto Contentis. columnas separadas están reservados para la numeración única, las necesidades reales y sus prioridades. Sin una mesa, la asignación de prioridades a las necesidades no habría sido tan claro como lo es aquí.

La Figura 23 muestra un extracto de la tabla que ilustra las características de varios productos de seguros que se utiliza para documentar la reingeniería

89

Informes de experiencia

conocido- en el momento

2001abril

conocido- en

reinstalado modi fi cada contrato niño añadió + prima de

el momento

2001abril

conocido- en

abril marzo

2001abril

2001

abril

febrero

2001

2001

marzo 2001

abril marzo

enero 2001-

2001

2001-

añadió modi prima fi ed

enero niño

2001 febrero

contrato original

2001 enero

contrato original

2001ene

niño

niño añadió + prima modi fi ed

febrero

2001

2001-

niño añadió + prima modi niño niño añadió + prima modi fi ed fi ed

2001

el momento

2001febrero

2001ene

2001 Mar

2001febrero

2001- Abr

niño añadió + prima modi fi ed

añadió modi prima fi ed

contrato original añadió modi prima fi ed

2001ene

2001 Mar

2001febrero

2001- Abr

2001 Mar

2001- Abr

efectividad a la hora

efectividad a la hora

efectividad a 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 tenía para el proyecto. Para todos los productos de seguros, la tabla indica claramente sus propiedades y demuestra por qué hablamos de TABLAS inequívoca.

La mesa era de gran utilidad para el equipo del proyecto, como el informe del proyecto explica.

90

La estructuración de los documentos individuales

1.3.2

¿Hay soporte para diferentes procesos de publicación?

UN

1.3.3

¿Qué canales publicación son compatibles?

segundo

1.4

Plantillas

1.4.1

¿Hay un editor de plantillas?

UN

1.4.2

Pueden plantillas de organizarse de forma jerárquica?

do

1.4.3

Pueden plantillas de heredar características de las plantillas de los padres?

do

1.4.4

Es el número de plantillas limitado?

UN

1.4.5

¿Las plantillas ofrecen soporte para marcos HTML?

segundo

1.4.6

Pueden incluir plantillas de código, como JSP?

UN

1.5

Importación y exportación

1.5.1

¿Qué mecanismos de importación no proporcionan el CMS (texto, gráficos, XML)?

UN

1.5.2

¿Qué formatos de impresión (PDF, etc.) se pueden importar?

UN

1.6

de versiones

1.6.1

¿Hay apoyo para la ramificación?

segundo

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

Proyecto liberarse: la información condensada en una tabla Especificando todos los productos de seguros y sus propiedades hasta el último detalle habría sido increíblemente compleja. Pronto resultó, sin embargo, que lo que el equipo necesita la mayoría era una visión general de todos los productos y sus propiedades - una lista o una tabla, algo sistemático. Como consecuencia, el equipo desarrolló una enorme hoja de cálculo en la que diversos tipos de propiedades fueron asignados a diversos tipos de productos de seguros.

Esta tabla de hoja de cálculo se creó primero al comienzo del proyecto, pero se mantiene y se actualiza durante casi dos años. Los desarrolladores y los clientes utilizan la hoja de cálculo en las reuniones cada vez que se discutieron cómo las propiedades del producto pueden ser modelados en el nuevo sistema. Hubo más documentación que acaba de esta hoja de cálculo, la documentación que proporcionó más detalles, pero era la hoja de cálculo que se utilizó en muchas discusiones y era más útil.

91

Informes de experiencia

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

complementar posibles dinámicas de

1948-1901 1955-1905 C 1 1 NNNRNNNNI

L1F 13 0003 REVISIÓN LFE

S COV

fecha de apertura

subtipo

L4S 61 0012 STD LFE 1990-1910

tipo

clave

L3f 53 0011 REVISIÓN LFE

fecha tope

L3R 52 0010 LFE RSK 1970-1901 1990-1910 C 3 1 NYNPNNNNI vieja llave

P COV P COV S COV

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

L4R 62 0013 LFE RSK 1990-1910 L4F 63 0014 REVISIÓN LFE LF

modo Política de niños fondos

tipo complemento de prima

1955-1905 1970-1901 C 2 1 NNNPNNNNI

L2F 23 0007 REVISIÓN LFE x

asegurados complementar

L2R 22 0006 LFE RSK 1955-1905 1970-1901 C 2 1 NNNPNNNNI

prima de terminación flexible de

obligatoria flexible prima reducida

XNNNPNNNNI

número de generación estado de los

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

1970-1901 1990-1910 C 3 1 NYNPNNNNI

1990-1910

70 0015 LFE ETS 1999-1901

P COV P COV P COV

O 4 1 NYNPPYNYI

P COV

O 4 1 NYNPPNNNI

P COV

O 4 1 NYNPPNNNI

P COV

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

P COV

1963-1907 1970-1901 C 2 1 NNNPNNNNI

P4 54 0020 PEN IMM 1970-1901 1990-1910 C 3 1 NNNRNNNNI

P COV

P4D 56 0021 PEN DEL

P COV

1970-1901 1990-1910 C 3 1 NYNPNNNNI

P5 64 0022 PEN IMM 1990-1910 P5D 66 0023 PEN DEL I1

15 0024

IG 18 0025

1990-1910

O 4 1 NNNRPNNNI

P COV

O 4 1 NYNPPNNNI

P COV

INV PRINCIPAL 1948-1901 1952-1907 C 1 1 NNNRNNNNI

P COV

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

INV SUP

P COV

I3S 57 0028 I4

65 0029

I4S 67 0030

1970-1901 1990-1910 C 3 1 NNNRNNNNI

INV PRINCIPAL 1990-1910

O 4 1 NNNRPNNNI

P COV

INV SUP

O 4 1 YNNRPNNNI

P COV

1990-1910

Figura extricate 23. Proyecto: una tabla que resume las propiedades del producto de seguro L1S 11

3

Diseño y la tipografía

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

Suzanne West (West 1990)

En un libro sobre la documentación ágil, un capítulo que trata de diseño y la tipografía había mejor empezar con una explicación. Casi puedo escuchar a la gente exclaman: '¿Qué diseño y la tipografía tiene que ver con un enfoque ágil? ¿Incluso importa?'

Sí, ellos son importantes, aunque de una manera bastante sutil. La mayoría 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 diseño y la calidad del diseño tiene una influencia sobre la legibilidad de un documento que no debe ser ignorada. Entonces, ¿cuál es la conexión de ser ágil? documentación á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 estándares de calidad con respecto a la disposición al igual que los libros impresos, y esto es por supuesto correcta. En una forma ágil los documentos del proyecto no pueden ir a través de un proceso de diseño muy largo: otras cosas son más importantes. Nuestro objetivo debe ser el de encontrar una manera rápida y fácil para producir documentos con un alto nivel de legibilidad.

Diseño y la tipografía

94

Permítanme apoyo la significación del diseño y la tipografía con los dos puntos siguientes. •

La tipografía es un antiguo arte. El arte de la impresión de libros se remonta muchos siglos, ganando impulso en 1454, cuando Johannes Gutenberg inventó la imprenta usando formas de letras reutilizables. reglas de composición tipográfica se han desarrollado y han madurado desde entonces. La gente no hubiera pasado tanto tiempo en la tipografía si no tuvo ningún efecto sobre la legibilidad.

•

La investigación se basa la significación del diseño y la tipografía. Miles Tinker llevó a cabo un sinfín de experimentos en el medio del siglo pasado y demostró que la mala tipografía ralentiza la lectura de forma significativa. Sus hallazgos se resumen en su libro sobre la Legibilidad de

impresión ( Gitano 1963). Un estudio realizado en 2000 reveló que la tipografía tuvo una influencia en la calidad de las propuestas a una importante agencia de financiación y el porcentaje de propuestas exitosas (Berleant 2000).

Aún sin estar convencido? Mira las páginas que se muestran en la Figura 24 y la Figura 25. Ambas páginas contienen el mismo material. ¿Qué prefieres leer? Todos estética a un lado, la página que cree usted que le permite recibir información de forma más rápida y más fiable?

Creo que es evidente que la segunda página es mucho más legible que la primera, y que diseño y la tipografía es lo que hace la diferencia entre los dos. Afortunadamente, el camino delante de nosotros en nuestro camino a una disposición como la de la figura 25 no es demasiado áspera - requiere menos trabajo que uno podría pensar a primera. Podemos obtener una razonablemente buena disposición para nuestros documentos de proyectos con muy poco esfuerzo, y esto es lo que los patrones en este capítulo se relacionan. Hay tres razones por las cuales se necesita poco esfuerzo para mejorar significativamente el diseño del documento:

1. Un bastante pequeño conjunto de patrones puede hacer mucho bien. La regla se aplica 80-20: 80 por ciento de las ofertas ventajas tipografía se puede obtener mediante el uso de un 20 por ciento de todas las técnicas disponibles tipográficos. Tras una actitud ágil, vamos a centrarnos en los patrones que describen estas técnicas. 2. Los patrones en este capítulo pueden ser fácilmente implementados en la mayoría 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 organización, el uso DOCUMENTO

95

- 20 -

4.2.1 Añadir un objeto addObject () EN OBJECTTYPE

: DT DE TIPO

EN Fullkey EN EntryDate EN processNumber

: DT-FECHA

: DT-KEY : DT-NR

Condiciones previas: ninguna

Función: La capa de acceso de datos proporciona una versión inicial de un nuevo objeto de acuerdo con la fecha de entrada y el número de proceso pasado a ella como parámetros. Tras la inicialización, el nuevo objeto todavía puede ser incompleta; componentes se pueden añadir sucesivamente. El estado del nuevo objeto está “pendiente”.

La clave que se pasa a esta función como un parámetro de entrada es una clave lógica, que pueden o no llevar información aplicación específica. Normalmente es generado por un módulo específico fi que todas las aplicaciones pueden utilizar. En caso de que la tecla fi cado se ha usado previamente para la adición de un objeto, se devuelve un código de error.

El número de proceso es generado por el sistema de gestión de fl ujo de trabajo. Códigos de retorno: RC-OK

El objeto se ha introducido y inicializado correctamente.

RC-KEY

La clave lógico especificado no está disponible.

RC-DB

La base de datos no está disponible.

RC-PARAMETROS

La fecha de entrada o el número de proceso son ilegales.

4.2.2 eliminar un objeto deleteObject () EN OBJECTTYPE

EN Fullkey EN deletionDate EN processNumber

: DT-typw : DT-KEY : DT-FECHA : DT-NR

Condiciones previas:

el objeto ha sido previamente añadido

Función:

Figura diseño 24. Page: una variación

Diseño y la tipografía

96

- 20 -

4.2.1 Adición de un objeto addObject () EN OBJECTTYPE

: DT DE TIPO

EN Fullkey EN EntryDate EN processNumber

: DT-KEY : DT-FECHA : DT-NR

Condiciones previas:

Ninguno Función:

La capa de acceso de datos proporciona una versión inicial de un nuevo objeto de acuerdo con la fecha de entrada y el número de proceso pasado a ella como parámetros. Tras la inicialización, el nuevo objeto todavía puede ser incompleta; componentes se pueden añadir sucesivamente. El estado del nuevo objeto está “pendiente”. La clave que se pasa a esta función como un parámetro de entrada es una clave lógica, que pueden o no llevar información aplicación específica. Normalmente es generado por un módulo específico fi que todas las aplicaciones pueden utilizar. En caso de que la tecla fi cado se ha usado previamente para la adición de un objeto, se devuelve un código de error.

El número de proceso es generado por el sistema de gestión de fl ujo de trabajo. Códigos de retorno:

RC-OK

El objeto se ha introducido y inicializado correctamente.

RC-KEY

La clave lógico especificado no está disponible.

RC-DB

La base de datos no está disponible.

RC-PARÁMETROS La fecha de entrada o el número de proceso son ilegales.

4.2.2 Eliminación de un objeto deleteObject () EN OBJECTTYPE

: DT DE TIPO

EN Fullkey EN deletionDate EN processNumber

: DT-KEY : DT-FECHA : DT-NR

Figura diseño 25. Page: otra variación

97

PLANTILLAS

para formar la base de todos los documentos del proyecto. Una vez que estas plantillas se han

diseñado de acuerdo a los patrones de diseño y la tipografía, los documentos del proyecto heredan el diseño gráfico de las plantillas. autores individuales fi reglas de composición tipográfica 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 características que ofrece el procesador de textos.

La figura 26 da una visión 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 más cómodo. Los patrones aseguran que la disposición es adecuada, si no es perfecto.

dos alfabetos se corresponde con

POR LÍNEA

permite para

120%

TEXTO EN 50% DE

interlineado

requiere

UN PÁGINA

usos El uso cuidadoso de

dos tipos de letra

variaciones de tipo

puede ser enriquecido por

combina bien

pueden formar

con

su colocación

COHERENTE PÁGINAS

exigir

adyacente

Figura 26. Patrones para el diseño y la tipografía

FALLO DE CUIDADO y sombreado

Diseño y la tipografía

98

Hay, por supuesto, muchas reglas más tipográficos, y los lectores interesados ​pueden consultar el rico cuerpo de literatura sobre la tipografía para más guías (Gulbins Kahrmann 1992, Tinker 1963 West 1990). Sin embargo, para obtener los documentos de proyectos que están razonablemente bien diseñado y que ofrecen un alto grado de legibilidad, los patrones en este capítulo, combinado con una buena dosis de sentido común, se bastar.

Una palabra final introductoria: los patrones en este capítulo se aplican a los documentos que se van a imprimir, pero no se aplican necesariamente a la documentación en línea. Tendremos una discusión acerca de lo MEDIA de fácil lectura En el Capítulo 4, lo que plantea la cuestión del frente de impresión de entrega de documentos en línea. Algunas pautas para la creación de documentos en línea se dan allí.

Texto en el 50% de una página Problema

¿Cuánto espacio en una página debe ser dedicado al texto?

Efectivo

El diseño de la página debe ser estético si se trata de ser agradable a los lectores. La estética de la geometría de la página son en gran medida influenciada por el tamaño de la denominada 'zona viva' - la zona en la que se coloca el texto principal, excluyendo los encabezados o pies de página. El área en vivo de una página está rodeado por los márgenes. Casi todos los lectores prefieren las páginas con amplios márgenes a las páginas que parecen estar llena de texto (West 1990).

Los márgenes no son necesarios por razones estéticas solamente, sino también por razones funcionales. El margen interior (también llamado el 'saco') debe permitir espacio suficiente para la unión. Todos los márgenes deben permitir suficiente espacio para que los lectores tienen una página sin ocultar cualquier texto (West 1990).

Sin embargo, los márgenes que son excesivamente grandes no son apropiados tampoco. Impresión de un documento requeriría más papel del necesario, lo que es indeseable para económico, así como razones ecológicas. Aparte del tamaño del área en vivo, su posición influye en la legibilidad de un documento. El centro óptico de una página es el lugar donde los ojos primero del lector se concentra. El centro óptico está ligeramente por encima del centro geométrico de la página. Por lo tanto, el área en vivo debe ser un poco más cerca de la parte superior que en la parte inferior de una página. En otras palabras, el tamaño óptimo margen es menor para el margen superior que para el margen inferior (Conover 1985 West 1990).

99

Texto en el 50% de una página

Solución

Alrededor del 50% de la página debe ser dedicado a texto. El resto de la página se reserva para los espacios en blanco, los encabezados y pies de página. Esta es una regla generalmente aceptada entre los expertos de diseño (Conover 1985, Tinker 1963 West 1990).

Para poner el centro del texto cerca del centro óptico, el texto debe colocarse más cerca de la parte superior que en la parte inferior de la página. Una proporción de 2: 3: 4: 5 entre los tamaños de la interior, superior, márgenes exteriores e inferior se recomienda a menudo, ya que permite el tamaño 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 página

Algunos documentos no diferencian entre las páginas de la izquierda y páginas de la derecha, por lo que los márgenes izquierdo y derecho son del mismo tamaño. En este caso, la relación de margen se puede ajustar a, por ejemplo, 3: 3: 3: 5. El margen inferior todavía debe ser mayor que el margen superior, sin embargo.

Para obtener una geometría de la página agradables, también se debe tener en cuenta lo siguiente:

•

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

•

El margen de canalón mínimo debe ser de 2 cm, para permitir la unión.

Diseño y la tipografía

100

•

Un área en vivo cubriendo poco más del 50% de la página es aceptable cuando no la totalidad del área en vivo es realmente cubiertos por texto, por ejemplo, debido a la utilización de cabezas secundarios que dejan suficiente espacio en blanco. 6

Una página estándar A4 tiene un tamaño de 21 × 29,7 cm. Aquí márgenes 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 página A4. tamaños de los márgenes similares se pueden utilizar para el formato de la carta de Estados Unidos (tamaño 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 página de carta de nosotros).

Discusión

La regla del 50% es de extrañar que muchas personas en el primero. Cuando la gente ve una página impresa, a menudo sobreestiman la cantidad de espacio dedicado a la zona en vivo y subestiman la cantidad de espacio dedicado a los márgenes. lectores medios estiman que el área en vivo abarca aproximadamente el 75% de una página, cuando, de hecho, cubre sólo el 50% (Tinker, 1963). En otras palabras, el 50% de texto es más de lo que parece.

Hay un límite en el ancho de la línea que indica que debe haber alrededor Dos alfabetos por línea, como se muestra en la Figura 28. Si más de dos y medio minúscula alfabetos fi t en una línea, la línea es demasiado ancho. Una vez que usted tiene de fi ne la zona en vivo de su página, usted debe comprobar si una línea a través de ella cumple esta regla, y de otra manera emplear técnicas para reducir el ancho de línea. Tener dos columnas por página es una opción, usando secundarios cabezas es otro, usando un tamaño de letra más grande es de un tercio.

Para dar a la zona un aspecto regular en vivo e incluso la textura, normalmente no más de DOS TIPOGRAFÍAS debe ser usado, y las líneas deben estar separados por 120% LINEA ESPACIADO.

Dos alfabetos por línea Problema Efectivo

¿Cuál es el ancho de la línea óptima? Al leer, los ojos del lector viajan a lo largo de la línea de izquierda a derecha. 7 Los ojos hacen pequeños movimientos espasmódicos, llamados 'movimientos sacádicos', entre los cuales hay períodos 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 párrafos reales, como se hace en este libro para los títulos de segundo nivel.

101

Dos alfabetos por línea

movimientos sacádicos son sólo 0,01 segundos de largo. Es durante las fijaciones que la información se recogió (Crowder 1982).

Un salto de línea interrumpe el movimiento del ojo a lo largo de la línea. los ojos del lector tienen que cambiar de nuevo al principio de la siguiente línea. líneas cortas aumentan el número de saltos de línea. Si las líneas son demasiado cortos, los ojos del lector tienen que hallar el comienzo de la siguiente línea más 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 líneas que son demasiado largos también hacen la lectura difícil y tedioso. Las líneas largas hacen que sea di fi culto para los ojos del lector a seguir una línea y de encontrar el comienzo de la siguiente línea una vez que se produce un salto de línea (Conover 1985, Gulbins Kahrmann 1992).

Por otra parte, el ancho de línea óptima depende del tamaño de fuente y el tipo utilizado. Tipo de establecer en tamaños más grandes requiere anchos de línea más largas (Conover 1985, Gulbins Kahrmann 1992).

Solución

Aproximadamente dos alfabetos minúsculas del tipo de letra estándar deben encajar en una línea. Como regla general, el límite inferior es alrededor de una hora y media alfabetos minúsculas, mientras que el límite superior se encuentra cerca de dos y un medio y como máximo tres alfabetos minúsculas (Gulbins Kahrmann 1992).

ABCDEFGHIJKLMNOPQRSTUVWXYZ abcdefghijklmnopqrstuvwxyz

Figura 28. Dos alfabetos por línea

7. Algunos idiomas no se escriben de izquierda a derecha, pero, por ejemplo, de arriba a abajo. Este patrón y el siguiente no se aplican a los documentos escritos en estos idiomas.

Diseño y la tipografía

102

Si las líneas son demasiado largos, hay varias maneras de fi x este problema:

•

Se puede elegir un tamaño de letra más grande.

•

Usted puede hacer las líneas más cortas mediante el aumento de los márgenes.

•

Usted puede hacer las líneas más cortas mediante el uso de dos columnas en lugar de uno.

•

Usted puede hacer las líneas más cortas mediante el uso de cabezales secundarios.

Discusión Cuando se elige para optimizar el ancho de línea, ya sea mediante el aumento de los márgenes o mediante el uso de dos columnas, usted debe asegurarse de que el diseño de la página se ajusta a la TEXTO EN 50% de una página

regla.

Justi fi texto ed puede ser problemático cuando el ancho de línea se encuentra cerca del límite inferior. Desde justificación 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 partición de palabras (West 1990). El uso irregular derecha en lugar de justificación también puede valer la pena considerar.

También hay un efecto sutil que el espaciamiento tiene en la gama de anchos de línea aceptables. Cuando el nivel de 120% interlineado se incrementa ligeramente, anchos de línea un poco por encima de dos y un medio alfabetos minúsculas pueden ser aceptables.

120% Interlineado Problema

¿Cuál es el espaciado de línea óptima?

Efectivo

Una textura uniforme es crucial para la legibilidad de un documento (West 1990). separación razonable entre las palabras y las líneas es un requisito previo para una textura uniforme. Mientras que la palabra separación es en gran medida determinado por el tipo de letra utilizado, espaciado de línea no lo es.

Si hay demasiado espacio entre líneas, líneas consecutivas ya no forman una unidad - que debería pero en vez parecen estar separados uno de otro. Esto hace que el texto di fi culto a leer (West 1990). espaciado de línea, sin embargo, no debe ser demasiado pequeña. Para explicar por qué, tenemos que entender que la línea de separación de los resultados de la suma del tamaño de letra para el 'líder' - el espacio real entre las líneas. Una cierta cantidad de conducir es necesario para asegurar que los ascendentes de una línea no colisionen con los trazos de la línea anterior. 8

120% Interlineado

103

Por otra parte, la aparición de un tipo de letra es influida por su altura x. 9 Un tipo de letra con una relativamente pequeña altura x parece ser más pequeño que su tamaño sugiere, y deja más espacio natural entre líneas, reduciendo así la necesidad de dirigir extra.

Solución

La mejor separación de líneas es aproximadamente 120% del tamaño de letra.

En otras palabras, 20% de ataque está normalmente fi ne. Para los tamaños de tipo estándar, tales como

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

abcdefgh klmnoxyz

100%

120%

espaciamiento Figura 29. Línea

Afortunadamente, la mayoría de los procesadores de texto establece el interlineado a aproximadamente 120% como valor por defecto, y así le proporcionan el espacio derecho alguno tamaño de letra que utiliza.

En los siguientes casos, la separación puede necesitar algo de fi ne-tuning:

Discusión

•

Espaciado se puede disminuir para tipos de letra con una relativamente pequeña altura x.

•

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

•

El espaciamiento debe aumentarse para líneas largas.

120 espaciado% línea es apropiado para el texto del cuerpo. Encabezamientos, sin embargo, son una excepción, ya que se supone que deben hacer que la estructura del texto visible. Para ayudar a los lectores perciben la estructura de un texto, títulos deben sobresalir no

8. un ascendente es la carrera de carta que se extiende por encima de la altura x de un carácter en minúscula; un descensor es un golpe de una letra minúscula que se extiende por debajo de la altura de la x.

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

Diseño y la tipografía

104

solamente por un aumento de tamaño tipo, sino también por un espaciado de línea que puede exceder 120%.

La anchura de la línea óptima se define por la Dos alfabetos POR LÍNEA patrón. Puede, sin embargo, esta regla doblar un poco. Si se aumenta la separación, las líneas que aumentan ligeramente la anchura de línea estándar aún serán aceptables. Sin embargo, esta técnica puede ser aplicada solamente en una pequeña parte. Si las líneas contienen significativamente más de dos y medio alfabetos minúsculas, que no son apropiadas, incluso con mayor espaciado.

dos Tipos de letra Problema Efectivo

¿Cuántos tipos de letra son apropiadas y que? Los procesadores de texto a menudo ofrecen una gran variedad de tipos de letra y tamaño de letra para elegir cada vez que los autores desean expresar los diferentes significados de texto puede tener, tales como títulos, é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 caótica: el uso de un gran número de tipos de letra es problemático, tanto por razones estéticas como por razones ergonómicas. 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 sólo un pequeño número de tipos de letra, cuáles debemos utilizar? Tipos de letra pueden expresar cosas tales como la solidez, la formalidad, la innovación, 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 líneas 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 más legible que sansserif tipos de letra, y por lo tanto deben tener preferencia. Sin embargo, las piezas individuales de texto impresos en una tipografía sans serif se destacan del texto principal y pueden atraer la atención del lector (Gulbins Kahrmann 1992).

105

dos Tipos de letra

Solución

En la mayoría de los casos, dos tipos de letra por documento son apropiados - un tipo de letra serif para el texto principal y una tipografía sans serif para los títulos.

También 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 más de dos tipos de letra es casi siempre inadecuada. Una posible excepción es el uso de un tercer tipo de letra para fragmentos de código incluidos en un documento. El tercer tipo de letra todavía debe utilizarse con moderación.

•

El tamaño 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 títulos de los capítulos 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 título. El cuerpo del texto

sansserif elegido para el título. El cuerpo del texto

se imprime en Garamond (11 puntos), que es un

se imprime en Times New Roman (11 puntos),

otro

tipo de letra serif.

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 cuestión de gusto personal. Los tipos de letra más tradicionales, como Veces y Garamond tienden a ofrecer una legibilidad superior a los tipos de letra más a la moda; Por lo tanto, parece más apropiado para la documentación 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 fácilmente se les puede decir aparte. Aún así, tienen que encajar juntos en un sentido estético. Ejemplos típicos son Veces y

Diseño y la tipografía

106

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

Discusión Cuando este patrón habla de 'texto del cuerpo', significa texto en los párrafos normales como así como el texto utilizado en las tablas o diagramas (con excepción de capturas de pantalla, copias de pizarra, etc.). No hay necesidad de utilizar diferentes tipos de letra en tablas o diagramas en comparación con el texto principal.

Tampoco existe una necesidad de expresar énfasis a través de diferentes tipos de letra. De hecho, es contrario a la intuición. Usted puede expresar todo tipo de énfasis necesarios por El uso cuidadoso de TIPO Variaciones.

El uso cuidadoso de las modificaciones de tipo Problema

¿Cómo 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 utilización de variaciones de tipo. palabras minúsculas normales aparecen en una forma característica definida por las ascendentes y descendentes de las letras. Una forma característica es crucial para la legibilidad de una palabra. Muchas variaciones de tipo no disponen de la forma característica tanto como un tipo de letra minúscula estándar 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 todavía tienen una forma característica. No obstante, cursiva disminuyen ligeramente la legibilidad del texto. Lectura de texto impreso en letra cursiva tarda aproximadamente 4% más de tiempo que la lectura del mismo texto impreso en un tipo minúsculas estándar (Tinker

1963). Las letras mayúsculas no cuentan con una forma característica en absoluto. Disminuyen la legibilidad del texto de manera espectacular. Leer el texto impreso en letras mayúsculas requiere alrededor de 12% más de tiempo que un texto normal (Tinker, 1963). Por otra parte, 'todas las tapas' no son apreciados por una gran mayoría de los lectores. Además, todas las tapas de romper el flujo de un texto.

Lo mismo es cierto para los subrayados. Destaca que solía ser una técnica común en las máquinas de escribir, que se disponía de ningún otro elemento de estilo. Pero ambos subrayados y todas las letras mayúsculas casi nunca se usan en los libros impresos.

107

El uso cuidadoso de las modificaciones de tipo

Solución

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 comúnmente 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 mayúsculas 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

Discusión

Puede utilizar los estilos de fuente especial cuando se organizan como un documento La información estructurada. Por ejemplo, negrita se utiliza a menudo para dejar Thumbnail Sketches

se destacan entre el resto del texto. Cursiva y casquillos pequeños pueden ser útiles para referencias a otros documentos. Utilizando subrayados es bastante común que los hipervínculos en documentos en línea. Esto puede ser justificado, pero los documentos impresos son un asunto diferente. Desde este capítulo

se trata de documentos impresos, sin embargo, no se recomiendan subrayados.

10. En contraste con todas las tapas, casquillos pequeños tienen claramente una sensación menos voluminoso, por lo que su uso ocasional está bien. Además, las pequeñas tapas se pueden ajustar con un capital principal, en cuyo caso se ofrecen algunos forma característica.

Diseño y la tipografía

108

Sentencia cuidado y sombreado Problema

¿Cómo se pueden separar celdas de la tabla?

Efectivo

Los documentos creados en los proyectos de software a menudo incluyen tablas. Para acceder fácilmente a la información 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 problemática, ya que un poco de espacio en blanco es necesaria si la separación de las células es a ser clara, en particular cuando las células de mesa se extienden sobre más de una línea. Si utiliza un espacio en blanco para separar celdas de la tabla, se pierde el espacio que de otra manera se podría utilizar para el texto.

Fallo es una técnica más eficaz para la separación de celdas de la tabla. Sin embargo, el fallo es definir sólo el tiempo que las líneas que rodean las celdas de la tabla tienen el espesor adecuado. Las líneas que son demasiado delgadas son difíciles de reconocer, mientras que las líneas que son demasiado gruesas no son estéticamente agradables y irritan el lector. Idealmente, las líneas 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.

Solución

Cuidado gobernante y el sombreado conduce a tablas altamente legibles.

Técnicamente, cuidado fallo y el sombreado significa lo siguiente:

•

Líneas que rodean celdas de la tabla tienen el espesor correcto si ellos son casi tan grueso como la letra mayúscula I (Gulbins Kahrmann 1992).

•

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

Se pueden combinar ambas técnicas, por ejemplo mediante el uso de fallo para separar celdas de la tabla y el sombreado para identificar el encabezado de la tabla.

109

La colocación adyacente

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

Discusión

Obviamente, con cuidado de fallo y el sombreado es útil a fin de lograr AMBIGÜEDADES MESAS, pero en realidad es aplicable a la presentación de La información 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 colocación adyacente Problema

¿Cómo pueden las tablas y diagramas pueden integrar en el texto?

Efectivo

La colocación de tablas y diagramas puede ser difícil. El lugar ideal para una tabla o diagrama está directamente debajo de la línea 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 página.

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

La idea obvia es insertar un salto de página entre el párrafo y el diagrama si el esquema no encaja en la página actual, lo que hace que el diagrama de aparecer en la página siguiente. Esta estrategia, sin embargo, es definir sólo si no hay gran espacio vacío se produce en la parte inferior de la página actual.

Diseño y la tipografía

110

A veces, sin embargo, se produce un gran espacio vacío. Especialmente diagramas grandes pueden causar páginas medio vacías, lo que es claramente indeseable. En tal caso, necesitamos para desacoplar el diagrama del párrafo en la que se hace referencia y a la que normalmente sería anclado. Es posible que tenga que colocar el diagrama en cualquier lugar cerca del punto, quizá más adelante, quizás por encima, tal vez en la página siguiente.

La consecuencia es que el párrafo 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 números, en lugar de por una expresión como 'el siguiente diagrama'. Lo mismo se aplica a las tablas si se quieren evitar los saltos de página dentro de las tablas.

Incluso la estrategia de desacoplamiento grandes diagramas o tablas en el texto de referencia podría no ser suficiente. Si un documento contiene un gran número de diagramas, puede que no haya suficiente texto para llenar los huecos dejados por los diagramas.

Solución

Diagramas y tablas están mejor cerca del texto de la que se hace referencia. Las siguientes técnicas pueden ayudarle a poner tablas y diagramas lo más cerca posible del punto de referencia como sea posible sin crear vacíos incómodos en la página: •

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 más 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 párrafo. se permite texto para llenar los vacíos.

•

tablas más grandes, de 4 filas en adelante, deben permitir los saltos de página.

•

Diagramas deben indicar también el número y deben ser referidos por sus números.

•

Si hay demasiados esquemas de integración sin problemas en el flujo de texto, mover al menos algunos de ellos en un apéndice puede ser preferible, ya que esto puede permitir que el texto flujo permanezca intacto. (Páginas semivacío son mucho más aceptable en un apéndice que en el texto principal).

Discusión

La mayoría de los procesadores de texto permiten el uso de marcos anclados en la que un diagrama puede ser colocado. Tal marco anclado se mueve automáticamente con el para-

111

Páginas coherentes

gráfico al que está anclado. Los buenos sistemas también permiten marcos anclados a ser definida como flotando, lo que significa que una trama se mantiene cerca del párrafo, pero se pueden colocar en la página siguiente si esto permite un mejor texto de flujo en la página actual. Si está disponible, seleccione esta opción para grandes diagramas. Permitir saltos de página en las tablas hace que la colocación de mesas más fácil. Aún así, los saltos de página en tablas sólo se debe permitir siempre y cuando no sacrificar PÁGINAS coherente.

Páginas coherentes Problema

¿Qué opciones existen para evitar la paginación incómoda que desgarra la información relacionada a pedazos?

Efectivo

Los saltos de página son una cosa perfectamente normal, sin embargo, algunos saltos de página parecen ser aceptable, mientras que otros no lo hacen. Los saltos de página son particularmente incómoda cuando se rompen el flujo innecesariamente y los lectores de fuerza para saltar hacia atrás y adelante. Este es el caso cada vez que un salto de página hace un pequeño fragmento de información aparece en una página y material relacionado aparecerá en la página siguiente o anterior. Un ejemplo es un encabezado de sección que aparece en la parte inferior de una página, mientras que el párrafo primero de esa sección aparece en la página siguiente. Otros son 'viuda' o líneas 'huérfanos'. Una viuda es la última línea de un párrafo que aparece aislada en la parte superior de una página, mientras que un huérfano es la primera línea de ficción de un párrafo que aparece aislada en la parte inferior de una página.

Tales saltos de página son irritantes y pueden hacer que sea di fi culto para los lectores a comprender una idea o línea de argumentación, especialmente para los lectores que navegan un documento rápidamente.

Solución

La lectura de flujo se apoya en las páginas coherentes - páginas que asegurarse de que aparezca un mínimo de información relacionada a cada lado de un salto de página.

Se puede lograr mediante el uso de páginas coherentes las siguientes reglas:

•

No hay encabezados deben aparecer en la parte inferior de una página. Un título siempre es seguido por al menos un párrafo que aparece en la misma página.

•

No hay líneas viudas o huérfanas. Al menos dos líneas de un párrafo deben mantenerse juntos en cada página.

Diseño y la tipografía

112

•

Las pequeñas mesas deben aparecer en una página. Si un salto de página debe ocurrir dentro de una tabla, se aplica la regla de la línea viuda: al menos dos filas de la tabla deben mantenerse juntos en cada página.

•

Discusión

No hay saltos de página dentro de celdas de la tabla.

Todas estas reglas pueden ser implementadas con procesadores de texto estándar con bastante facilidad. Es necesario para no permitir líneas viuda y huérfanos para todos los tipos de párrafo y de obligar a todos los tipos de párrafo para los títulos que se le mantenga con cualquier párrafo que sigue. También hay que rechazar los saltos de página para los tipos de párrafos utilizados en celdas de la tabla - que por supuesto requiere que los distintos tipos de párrafos pueden utilizar en celdas de la tabla. Sólo los saltos de página dentro de las tablas (en lugar de dentro de las células de mesa) pueden requerir intervención manual.

páginas coherentes pueden adoptar una forma ligeramente diferente en el contexto de ESTRUCTURADO INFORMACIÓN. Usted puede decidir no permitir saltos de página dentro de los bloques de construcción. Si uno mira hacia atrás en la Figura 12 en la página 69, se ve una página que consiste en un encabezamiento y cuatro bloques. Tal estructura de pro fi cios de no ser interrumpidos por saltos de página. Sin embargo, si los bloques de construcción se hacen más grandes, debe permitir que los saltos de página, de lo contrario páginas medio vacías sería la consecuencia - una contradicción de tener TEXTO EN 50% de una página.

Informes de experiencia Hay infinidad de ejemplos de los patrones tipográficos descritos en este capítulo. Puede fi nd casos de estos patrones en casi todos los libros impresos - los patrones son una práctica común. 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 también se pueden utilizar en la documentación del proyecto con facilidad. La figura 33 muestra la página que ya sabemos desde el principio de este capítulo, tomado del concepto de uso del Proyecto persistor. La Figura 34 muestra una página del documento de requisitos de Proyecto Contentis. Anotaciones señalan que se han aplicado los patrones, y cómo. 11

11. No se deje sorprender por la relativamente pequeña fuente en estos ejemplos. Los documentos originales eran A4 y tuvo que ser reducido para ajustarse al tamaño de la página de este libro. La fuente original hizo permitir la lectura cómoda.

113

Informes de experiencia

buena

- 20 -

paginación

4.2.1 Adición de un objeto addObject ()

razonable

EN OBJECTTYPE

: DT DE TIPO

EN Fullkey EN EntryDate EN processNumber

: DT-KEY : DT-FECHA : DT-NR

uso de negrita

Condiciones previas:

Ninguno Función:

La capa de acceso de datos proporciona una versión inicial de un nuevo objeto de acuerdo con la fecha de entrada y el número de proceso pasado a ella como parámetros. Tras la inicialización, el nuevo objeto todavía puede ser incompleta; componentes se pueden añadir

el texto, uno para el código

sucesivamente. El estado del nuevo objeto está “pendiente”. La clave que se pasa a esta función como un parámetro de entrada es una clave lógica, que pueden o no llevar información aplicación específica. Normalmente es generado por un módulo específico fi que todas las aplicaciones pueden utilizar. En caso de que la tecla fi cado se ha usado previamente para la adición de un objeto, se devuelve un código de error.

buena separación y la

El número de proceso es generado por el sistema de gestión de fl ujo de trabajo. Códigos de retorno:

RC-OK

El objeto se ha introducido y inicializado correctamente.

RC-KEY

La clave lógico especificado no está disponible.

RC-DB

La base de datos no está disponible.

anchura de la línea encabezados, uno para

buena colocación de la tabla

RC-PARÁMETROS La fecha de entrada o el número de proceso son ilegales. de letra para los

4.2.2 Eliminación de un objeto

fallo y el sombreado

deleteObject ()

adecuado

EN OBJECTTYPE

: DT DE TIPO

EN Fullkey EN deletionDate EN processNumber

: DT-KEY : DT-FECHA : DT-NR lo suficientemente blancos espacio de un tipo

Figura 33. Proyecto persistor: buen diseño y la tipografía

Diseño y la tipografía

114

- 20 paginación

4.2 Boletín de despliegue La distribución de un boletín consta de varios pasos que todo ser soportados por el sistema de gestión de contenido web. Estos pasos son:

un tipo de letra para

1. Meta información

el texto, uno para los

Meta información incluye el boletín de noticias del autor, título, tema y fecha de lanzamiento. El CMS ofrece una interfaz web para que los usuarios proporcionan esta información. Además, el sistema proporciona el número y la fecha de grabación. Este meta-información es necesaria para mejorar las capacidades de

títulos y

diagramas reglas de la

búsqueda. 2. Texto principal El editor responsable escribe el texto para el boletín de noticias usando el editor Web del sistema de gestión de contenidos ofrece. herramientas de formato están disponibles que permiten al editor para elegir tamaño y tipo de letra estilos de fuente. espaciamiento y

3. Adjuntos La mayoría de los boletines de noticias vienen con uno o más archivos adjuntos, como documentos, páginas web, o presentaciones. El editor agrega estos archivos adjuntos al boletín de noticias utilizando una función del sistema de

anchura de la línea de encuentro del Unas buenas

gestión de contenidos proporciona.

4. Generación de documentos Una vez que todos los elementos de la letra de noticias se han reunido, el editor puede hacer clic en un botón, y así seleccionar la función que genera un archivo PDF para el boletín de noticias, y luego invoca el módulo de flujo de trabajo para el proceso de revisión.

5. Revisión El departamento de jefes de recibe un mensaje de que el boletín está listo para su revisión, y puede aceptar, modificar o rechazar el boletín. Una vez aceptado, el boletín se copia en el entorno de producción del sistema de gestión de contenidos, y por lo tanto disponible dentro de

diagrama bien colocado

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 Generación de documentos

diagrama

Comentarios

Higo. 5: Proceso de implementación para boletines

cursiva para los subtítulos

Figura 34. Proyecto Contentis: otro ejemplo de diseño y la tipografía

115

Informes de experiencia

A pesar de todos los documentos de ejemplo incluyen casi todos los patrones de este capítulo, no tienen el mismo diseño. Se puede ver que los patrones tipográficos presentados dejan un amplio margen para la creatividad - o para el seguimiento de las directrices de diseño que tienen para una organización o un proyecto. Los patrones proporcionan un marco para aumentar la legibilidad y la estética de los documentos impresos, pero dejan mucho de su aplicación abierta. Puede aplicar los patrones tipográficos de muchas maneras diferentes y creativas.

4

infraestructura y técnica Organización

La gestión de la documentación y gestión de software es esencialmente la misma cosa.

Anónimo

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 diseño. Este capítulo se centra en las herramientas y técnicas que podemos utilizar para obtener dichos documentos ya ponerlos a disposición de un equipo de proyecto. Entre otras cosas, los documentos tienen que ser procesados ​e impresos, almacenados y recuperados.

En resumen, este capítulo nos lleva a la cuestión de lo que la infraestructura de la documentación debe ser similar y cómo puede ser organizada. Me gustaría empezar con un ejemplo que demuestra por qué es necesaria la organización de la infraestructura de la documentación. 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 simbólicos completan la confusión. 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 habían escrito más o menos en cualquier lugar. Más de una vez que alguien asume un documento no existe, cuando en realidad sólo estaba oculto en el caos. versiones redundantes de docu-

118

Infraestructura y Organización Técnica

Figura 35. documentación del proyecto mal organizados

119

READERFRIENDLY

CODIGO-COMENTARIO

PROXIMIDAD

depender de

MEDIA

complemento

SEPARACIÓN DE PROCESAMIENTO Y IMPRESIÓN

puede

requiere

depender de

requerir

exigir rendimientos

NOTIFICACIÓN EN ACTUALIZAR

CONTENIDO Y

DISEÑO

plantillas de

se refiere a los

es una condición previa

SEPARACIÓN DE para

documentos

documentos

en el

reside en

puede

FUENTE simple y puede ayudar a

referirse a

múltiple

mantener la

referirse a los documentos

OBJETIVOS DE

documento

en el

horizontal

someterse a

puede ayudar a mantener la

se almacena a

CAMBIOS

IMPORTACIONES

menudo en

ANOTADOS

POR REFERENCIA

un

sufre DOCUMENTO DE

deben ser

ARCHIVO

implementadas con

afecta

puede ser representada

sufre

por una puede ser respaldada

con una POCOS HERRAMIENTAS

WIKI

REORGANIZACIÓN A sufre requieren

Figura 36. Patrones de infraestructura y organización técnica

PETICIÓN

Infraestructura y Organización Técnica

120

mentos se mantuvieron, inconsistencias se produjeron y versiones obsoletas eran la fuente de mucha confusión. Ciertamente queremos evitar un escenario de este tipo, y yo creo que está claro en este ejemplo que es necesario un poco de organización. Pero la cantidad de organización necesitamos? Después de todo, el exceso de organización 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 producción y mantenimiento de la documentación se refiere? Hay mucho valor en las herramientas si hacen nuestro trabajo más fácil, pero un exceso de énfasis en las herramientas no es ágil tampoco.

Estas preguntas demarcan el área que los patrones en esta dirección capítulo. Los patrones se ocupan de la organización técnica de todos los documentos producidos en un proyecto, de sólo un puñado de papeles cortos a la documentación completa encontraron en proyectos o proyectos de mayor envergadura con una criticidad superior. La Figura 36 proporciona una visión general.

Los patrones no pueden proporcionar soluciones prefabricadas para todos los problemas asociados con la organización técnica de los documentos del proyecto - la documentación 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 creación y el mantenimiento de los documentos del proyecto y la gestión de las relaciones entre ellos.

Paisaje documento Problema

¿Cómo pueden los miembros del equipo tengan una buena visión general de lo que existe en la documentación de un proyecto?

Efectivo

Documentación, cuando está mal organizada, en última instancia, se producirá un error de servir a su propósito general de hacer la experiencia del proyecto a disposición de otros miembros del equipo y de los proyectos futuros. No hay ningún punto en la producción de documentos si los lectores potenciales no saben que existen. En un nivel más técnico, la organización de la documentación del proyecto debe servir a dos propósitos: autores entre los miembros del equipo se les debe decir cómo integrar nuevos documentos en la documentación existente, y los lectores se les debe decir dónde buscar documentos específicos.

¿Cómo es una organización así como? Con este fin, es útil recordar que los documentos de proyectos a menudo están conectados por diversos tipos de

Paisaje documento

121

las relaciones, y para examinar cómo los seres humanos organizan los elementos relacionados en sus mentes.

La psicología cognitiva nos dice que los seres humanos pueden representar conjuntos de elementos relacionados como imágenes mentales, o paisajes en nuestra mente. En su libro ¿Cómo 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 sólo imagina este paisaje, pero cuando navegamos la documentación, 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 fáciles de seguir si abarcan un árbol (Botafogo Rivlin Shneiderman 1992) - un árbol representa un equilibrio entre la estructura y la comprensibilidad. Al parecer, la mayoría de los usuarios prefieren un amplio árbol a una estrecha uno: en la mayoría 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 múltiples puntos de entrada parecen ser fi ne (Furnas Zacks 1994).

Solución

La documentación 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 añadir información. Un paisaje documento que más o menos se forma un árbol se adapte mejor intuición humana.

Idealmente, el paisaje documento sigue la estructura del proyecto. La figura 37 muestra un ejemplo. Los documentos se agrupan si están estrechamente relacionados. Este paisaje presenta una forma intuitiva de representar la documentación del proyecto. No es estático, sin embargo, pero evoluciona a medida que el proyecto continúa. Hay varias formas en que se pueden implementar un paisaje documento:

•

La forma más sencilla es utilizar fi l de directorios y subdirectorios del sistema. Asociar directorios con temas conduce a una organización fácil, pero e fi ciente, siempre y cuando no hay solapamientos ocasionados por temas ortogonales.

•

Además, 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 introducción. Ese documento describe el proyecto y explica lo que existen otros documentos, su propósito y la forma en que se pueden obtener.

Infraestructura y Organización Técnica

122

Resumen del sistema

Requisito

visión general

específico catión

del diseño

requisitos de prueba

Casos de prueba

Módulo especificaciones

Figura 37. Un paisaje documento

•

Se puede poner el paisaje de documentos en línea con hipervínculos actuando como vías de acceso a los documentos reales, lo que permite a los usuarios viajar en realidad a través del paisaje documento.

Discusión ¿Qué técnica se debe preferir? Acecho detrás de esta pregunta es la deseo de utilizar MEDIA de fácil lectura en la presentación de información. Debido a su alto grado de referencialidad, el paisaje documento a menudo se presenta mejor en línea. Si le das a todos los miembros del equipo de lectura y escritura, el paisaje documento equivale a un proyecto WIKI. Si una presentación en línea es el medio de elección depende en última instancia del escenario típico en el que el OBJETIVO LECTORES

utilizará el paisaje documento. Una cuestión 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 línea, si se ha mejorado con un motor de búsqueda? En grandes proyectos de esto puede ser vale la pena considerar. La utilidad de un motor de búsqueda está generalmente limitada, sin embargo, ya que los motores de búsqueda sufren de una solución de compromiso entre el recuerdo y la precisión. Recordar y de precisión

123

Archivo de documentos

normalmente sumar el 100 por ciento (Salton 1989) 12: 50 por ciento de recordatorio y 50 por ciento de precisión pueden ser considerados un resultado típico (Dumais 1988). Sin embargo, un motor de búsqueda puede resultar útil si un gran número de documentos tienen que ser gestionados y la visión general propuesta por el paisaje documento, sin embargo útil, no es totalmente su fi ciente.

Usted puede sentir la importancia de este patrón con una analogía 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 documentación de un proyecto completo. Por último, el grado de cohesión del documento del paisaje que ofrece información sobre qué tan bien la documentación del proyecto cumple con el objetivo de presentar La información centrada. Si resulta ser difícil de encontrar una estructura adecuada para el paisaje de documentos, una falta de concentración en los documentos individuales puede ser la causa, capaces de dar lugar a AR eorganisation de

el proyecto documentación.

Archivo de documentos Problema

¿Cómo pueden los proyectos de evitar la pérdida de cualquiera de las versiones de documentos?

Efectivo

Los documentos del proyecto están organizados típicamente 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 rápidamente.

Sin embargo, muchos documentos se someten a cambio como un proyecto continúa. Puede llegar a ser necesario rastrear la información en una versión anterior de un documento. Por lo tanto, a veces no es su fi ciente para mantener sólo las versiones más recientes de todos los documentos.

Aún 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 sólo cuando realmente necesitan para hacerlo.

12. Recordar describe cómo gran parte de la información relevante se encuentra, mientras precisión describe cómo gran parte de la información que se encuentra es relevante. Si una búsqueda produce el 80% de toda la información pertinente, a continuación, sólo alrededor del 20% de los resultados son relevantes - los otros resultados han deslizado simplemente debido a la falta de precisión. Si restringe los parámetros de búsqueda 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.

Infraestructura y Organización Técnica

124

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 versión, al mismo tiempo, anulando el trabajo del otro. Por último, hay que tener en cuenta que los problemas técnicos, tales como accidentes de disco duro pueden conducir a la documentación del proyecto están perdiendo. Esto suena trivial, pero mucho daño ya está hecho, arruinando el trabajo de semanas o meses, por un fallo de hardware.

Solución

documentación 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 sofisticación.

•

La forma más simple de archivo consiste en una convención 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 documentación del proyecto.

•

Un sistema de gestión de con fi guración ofrece más 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 automáticamente versiones antiguas y las recupera a petición (Berczuk Appelton 2003).

Como tenemos la intención de utilizar las herramientas más sencillas que ful fi l nuestros propósitos, 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 gestión con fi guración de todos modos, en especial para el código fuente. En este caso, la segunda opción no representa un esfuerzo adicional y está bien vale la pena considerar. Un sistema de gestión de configuración bastante simple con fi suele ser el caso, ya que los sistemas complejos requieren un esfuerzo de aprendizaje que es raramente justificado.

Discusión

La creación 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 más estrecha

ing del término, el archivo no implica necesariamente que las versiones antiguas pueden mover a los medios de almacenamiento fuera de línea para fines tales como liberando espacio.

125

wiki

en carpetas y, posiblemente, subcarpetas, ya sea en el sistema fi le o en un sistema de gestión de configuración con fi.

wiki Problema

¿Cómo puede la documentación se dará una ventaja más interactivo?

Efectivo

Documentación tiene mucho a su favor, a largo plazo y amplia disponibilidad, entre otras cosas. Sin embargo, la interacción es importante en un equipo de colaboración. La gente tiene preguntas o le gustaría dar respuestas. Se ha dicho muchas veces antes: la documentación y la interacción 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 también sabe la respuesta, pero no se sabe quién podría ser esa persona.

Con este fin, el apoyo técnico para la combinación de la documentación y la interacción podría ser útil. Lo que podría apoyar parecerse? Su objetivo debe ser aumentar la interacción entre el equipo, sino que también debe tener en cuenta que podría ser necesaria una comunicación asíncrona.

Solución

Un Wiki ofrece acceso a la documentación del proyecto a través de un servidor de intranet, y, además, permite al equipo para publicar notas y mensajes a otros según 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 demás.

14. 'Wiki' es la palabra hawaiana para 'rápido'. El término 'Wiki Web' se introdujo por Ward Cunningham para sitios web de colaboración que dan a sus usuarios de rápida lectura y escritura (Leuf Cunningham 2001).

Infraestructura y Organización Técnica

126

En otras palabras, un Wiki es un foro de comunicación asíncrona sin embargo colaboración interactiva.

Discusión

Un Wiki implementa el proyecto de documento horizontal y permite a los miembros del equipo para navegar a través 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 restricción 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 todavía puede hacer copias de seguridad. Un equipo de proyecto, sin embargo, no es una masa anónima, y ​el acceso general para todo el mundo no debería representar un problema. Sin embargo, la mayoría 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 interacción que un simple archivo no, el establecimiento de un Wiki que pone en su camino hacia una INFORMACIÓN MERCADO

en la que los documentos se ofrecen e intercambian de forma activa.

Código-comentario de proximidad Problema

¿Cuál es una manera fácil de mantener la documentación que hace referencia al código real?

Efectivo

La documentación puede tomar diferentes formas. En primer lugar, la documentación consta de los documentos que se producen en un proyecto. En segundo lugar, la documentación cubre los comentarios que los programadores ponen en el código fuente, que no deben ser ignorados. La pregunta aquí es, que tipo de documentación deberíamos preferir?

Una cierta proximidad de código 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 código fuente son relativamente fáciles de mantener. Si cambia algo en un programa y su documentación se encuentra en otro lugar, lo más probable es que se olvide de cambiar la documentación correspondiente.

127

Código-comentario de proximidad

Las actualizaciones son mucho más fácil si todo lo que necesita hacer es actualizar algunos comentarios en el código.

Programación literaria va un paso más allá. Programación literaria denota un estilo de programación 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 selección de los nombres de las variables es particularmente importante. Lo ideal sería que un programa se convierte en un texto que no necesita más comentarios.

Pero, ¿es siempre posible? No todos los temas que requiere la documentación está directamente relacionada con el código. Hay temas de nivel superior, tales como las necesidades del usuario o la arquitectura de software que no pueden ser relacionados con las líneas individuales de código y que son, por tanto, más allá de lo que puede ser documentada dentro de un programa.

Solución

Documentación del código, en la medida en que un equipo de proyecto considera necesario, es mejor hacerlo a través de comentarios de código fuente. documentos separados deben reservarse para problemas de nivel superior, tales como resúmenes, requisitos, diseño y arquitectura. Las siguientes pautas le ayudarán a hacer comentarios de código tan simple como sea posible.

•

Mantener el software lo más claro posible, por ejemplo a través de nombres bien elegidos para objetos y funciones.

•

Añadir comentarios sólo cuando el código sola no proporciona suficiente información, y guardan las observaciones cerca del código al que se refieren. La proximidad de código y los comentarios correspondientes hace que los comentarios relativamente fáciles de mantener. Cada vez que se cambia el código, usted tiene los comentarios correspondientes justo en frente de usted y usted puede cambiar en consecuencia. Las actualizaciones de documentos sólo serán necesarias cuando los cambios afectan a algo más que el código, tales como el diseño general.

Discusión

Este patrón ya se toca el tema de la MEDIA de fácil lectura. Ese patrón se centra en la cuestión de la elección de los medios para los documentos del proyecto, pero esa pregunta es razonable sólo si estamos seguros de que un documento es el medio adecuado en absoluto. El patrón actual señala que cierta información puede no ser necesario un documento, y que la información está mejor conservado dentro del programa.

Infraestructura y Organización Técnica

128

De fácil lectura-Medios Problema

¿Qué es más apropiado: los documentos destinados a ser utilizados en línea o documentos destinados a la impresión?

Efectivo

Por razones ergonómicas, la mayoría de las personas prefieren leer documentos en papel en lugar de documentos en línea. Esto es cierto en particular para los documentos más largos que los lectores pueden dedicar más tiempo a la lectura. Los documentos impresos ofrecen una mejor resolución y contraste de una pantalla de ordenador, documentos impresos no necesitan una fuente de alimentación eléctrica, 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 fácilmente 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 serán reemplazados por versiones electrónicas. Hay avances tecnológicos en lo que se refiere a la ergonomía de los documentos electrónicos (Press 2000). Pero, por el momento, la mayoría 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. Sólo documentos electrónicos ofrecen mecanismos tales como enlaces de navegación que hacen de tales referencias fácil. Los lectores tienen que utilizar documentos en línea si desean utilizar tales características (Hsu Mitchell

1997). Por otra parte, las presentaciones en línea pueden permitir a los lectores a jugar un papel más activo. En un escenario avanzado, los lectores pueden participar si la documentación incluye una simulación o una animación, aunque esto es bastante poco común para la documentación de los proyectos de software normales.

Hay dos argumentos más que parecen sugerir una ventaja que los documentos en línea tienen sobre los documentos impresos. Ni el argumento es válido, pero ambos deben mencionarse para mayor claridad.

En primer lugar, puede sonar interesante presentar los documentos rápidamente cambiantes en línea, con la esperanza de que los lectores leen automáticamente las versiones más 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 impresión en el primer lugar fi, por lo que no se dan cuenta cuando hay una actualización disponible en línea.

129

De fácil lectura-Medios

En segundo lugar, el uso de motores de búsqueda se utiliza a veces como un argumento para documentos electrónicos, pero esto no es un argumento válido tampoco. La aplicación de un motor de búsqueda de un documento requiere que el documento estará disponible electrónicamente, 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 línea puede .

Solución

La elección de un medio debe reflejar el uso típico de un documento. La regla de oro es: impresión es buena para la lectura, en línea es bueno para mirar las cosas.

Las siguientes pautas pueden ayudar a tomar la decisión. •

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 están 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'. Más bien, la gente toma un breve vistazo a esos documentos, o navegar a través de ellos, a menudo durante la programación o el diseño, por lo general el gasto sólo un corto período de tiempo en ellos. Tales documentos se presentan mejor en línea.

La siguiente tabla resume qué medio está normalmente el más adecuado para varios tipos de documentos. Impresión

En línea

Viabilidad del concepto de estudio o

Descripción de la arquitectura del

documento de estrategia de arquitectura

paisaje documento API descripción

visión general especí fi cación de

en esta guía del usuario Ayuda en

documentos Diseño Resumen concepto

línea On-line Glosario de simulación

de uso Gestión Glosario

Infraestructura y Organización Técnica

130

Como muestra la tabla, no hay una clara separación entre los documentos que se presentan como la mejor impresión y los que se presentan mejor en la línea. El panorama arquitectónico aparece en la impresión y en línea, 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 línea, y todos tienen razones de su elección. Esto sucede con los documentos que algunos lectores leer de principio a fin, pero que otros utilizan para buscar información y referencias para los siguientes. En este caso satisfacer las necesidades de los lectores requiere que se proporcione ambos una versión imprimible y una versión en línea.

Discusión

Si un documento es necesario tanto en papel como en línea, a veces es tentador para configurar el documento para su uso en línea y utilizar la misma versión para imprimir. Además de la reducción del esfuerzo, esto tiene la ventaja de que la información 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 línea para la impresión debe ser evitado por razones ergonómicas. Es una idea mucho mejor para generar la versión en línea de forma automática - una característica que muchos procesadores de texto ofrecen, y que evita la redundancia. La generación de documentos en línea de forma automática no sólo es útil cuando se requiere tanto una impresión de una versión en línea. Típicos documentos en línea - los que no se lee, pero sólo navegar a través de, los que tienen muchas referencias - a menudo pueden ser extraídos de otras fuentes. Por ejemplo, una descripción API a menudo se puede obtener de comentarios de código fuente. La generación de documentos en línea es una buena idea siempre que sea posible, ya que evita inconsistencias manteniendo una FUENTE ÚNICA Y OBJETIVOS DE MÚLTIPLES.

La decisión sobre los medios de comunicación 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 cación. La decisión, por lo tanto fuertemente influye en la definición de DOCUMENTO PLANTILLAS

que forman la base para varios documentos del mismo tipo.

Diferentes medios colocan diferentes requisitos de diseño y formato. Los documentos que se van a imprimir deben seguir las directrices que se presentan en el Capítulo 3 de Diseño y la tipografía. Estas directrices, sin embargo, no necesariamente se aplican a documentos en línea.

Separación de Contenido y disposición

131

Por lo que en línea se refiere a la documentación, las pautas a seguir son esencialmente los indicados en la literatura para la organización de los sitios Web. Puesto que este libro tiene su foco principal en documentos impresos, tales directrices están fuera de su alcance, pero la literatura ofrece un montón de fuentes. Un ejemplo es el libro de Jakob Nielsen Usabilidad Web Proyectos ( Nielsen 2000), otro es el libro de William Horton El diseño y la documentación en línea de escritura ( Horton 1994). Documentación en línea también está sujeto a los patrones: Robert Orenstein ha publicado una Lengua

del patrón para un sitio Web de Ensayo-base ( Orenstein 1996). Entre otras cosas, se recomienda De poca profundidad árboles de documentos y un Sección

introductoria con un Imagen de introducción.

Separación de Contenido y disposición Problema

¿Cómo pueden los diseños de documentos de texto pueden modificar y volver a utilizar fácilmente?

Efectivo

El diseño de un documento puede tener que cambiar. En primer lugar, es posible que tenga que adaptar el diseño para cumplir con alguna norma, tal vez siguiendo directrices específicas, tal vez siguiendo la petición de un cliente. En segundo lugar, y más probable, es posible que tenga que soportar un canal de salida adicional: tal vez un documento de impresión debe estar disponible para su uso en línea también.

Pasando por todos los párrafos 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 diseño de forma manual, o si una herramienta está disponible, cambios en el diseño, no vuelva a ser actividades de alto coste.

Por otra parte, una vez que un buen diseño ha sido diseñado, queremos ser capaces de volver a utilizarlo para otros documentos también. ¿Cómo podemos hacer eso? Si echamos un vistazo a los sistemas de gestión de contenidos, podemos ver lo que una posible solución podría ser similar. sistemas de gestión de contenidos desacoplan contenidos y diseño: graban el contenido sin formatear, por un lado, y por otro proporcionan mecanismos de fi ne estilos de diseño. El grado de sofisticación que se encuentra en los sistemas de gestión de contenidos es innecesario para los documentos de proyectos ordinarios, pero los indicios principio subyacente en una dirección que puede tomar.

Infraestructura y Organización Técnica

132

Solución

estilos de diseño pueden ser de fi nido y se asigna a porciones de contenido. Estos estilos de diseño se pueden cambiar fácilmente y se pueden reutilizar a través de los documentos.

El uso de un típico procesador de textos, la separación de contenido y el diseño se puede implementar muy fácilmente de la siguiente manera:

•

Definen los tipos de párrafo adicional en su documento.

•

Asignar un formato a cada tipo de párrafo.

•

Asignar un tipo de párrafo para cada párrafo, y así determinar la disposición de ese párrafo.

•

Evitar cualquier anulación del formato de un párrafo que ha sido asignada por su tipo.

Esta aplicación se ilustra en la Figura 38. Otra opción, aunque menos común, 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, podría escribir documentos en HTML, y proporcionar el formato a través de las hojas de estilo (CSS).

En cualquier caso, el cambio de la definición del trazado afecta a todo el documento en consonancia, siempre que se utilice el estilo de diseño en particular. La reutilización de los estilos de diseño en otros documentos no es un problema.

Discusión

Este patrón es la condición previa para otros dos patrones. En primer lugar, sin una separación de contenido o de presentación plantillas de documentos no sería 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 automática, lo que nos da una FUENTE ÚNICA Y OBJETIVOS DE MÚLTIPLES.

un mecanismo de este tipo se utiliza a menudo para asignar un formato

diferente para el mismo contenido, por ejemplo para generar código HTML de texto bien formateado. Tal mecanismo no podía llevarse a cabo sin la separación de contenido y el diseño.

Cuando se utiliza un procesador de textos, es probable que encontramos la separación de contenido y el diseño a ser un poco difícil si lo siguen hasta el último detalle. De hecho, incluso los expertos de autoedición han sido vistos sin obedecer la disposición del párrafo vez en cuando, cuando sentían la definición de un texto de párrafo extra no estaba justificado. Esto es aceptable siempre y cuando sea una excepción, y siempre y cuando usted sabe que usted está negociando flexibilidad de diseño fl de

133

Fuente única y Objetivos Múltiples

Título

Solución

Sans-serif 14point, negrita, sin sangría

estilos de diseño pueden ser de fi nido y se asigna a porciones de contenido.

bala

En un procesador de texto, esto significa:

•

De fi ne los tipos de párrafos Bloquear

•

Asignar formatos a estos tipos

•

Asignar un tipo a cada

miniatura de

sangría 11point serif, sin sangría bala serif 11point, negrita, sin 11point serif, la sangría, una

párrafo •

Evitar las anulaciones

Figura 38. Separación de los contenidos y el diseño como realizadas por un procesador de textos

conveniencia momentánea. En última instancia, las anulaciones rompen el concepto de DOCUMENTO PLANTILLAS y Sacrificio sus ventajas. Ya sea una separación limitada de contenidos y el diseño 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 diseño.

Fuente única y Objetivos Múltiples Problema

¿Cómo pueden los múltiples 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 versión imprimible y una versión HTML de una

Infraestructura y Organización Técnica

134

documento. La preparación de un documento separado de formato, sin embargo, conduce a redundante documentos. O considerar los comentarios en el código fuente que describen, por ejemplo, interfaces de clase en un lado y una descripción de la API HTML en el otro. Tal vez no pueden, o no quieren, Sacrificio tampoco. Una vez más, la redundancia se produce.

Podemos ver en estos escenarios que la información redundante, no siempre se puede evitar.

Redundancia, sin embargo, crea numerosos problemas - esto es tan cierto para la documentación, ya que es para el software. Cuando la información 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 fácilmente. 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 información, y que no hay necesidad de mantener más de un original.

Solución

La infraestructura de la documentación puede emplear mecanismos que tienen documentos de origen y generan automáticamente vistas adicionales. Tales mecanismos evitar la doble mantenimiento y garantizar la coherencia.

Si bien esta técnica no evita la redundancia, no administrarlo: sólo el documento de origen tiene que ser mantenido. Los siguientes mecanismos son ejemplos destacados:

• •

La mayoría 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 código fuente. Una cuestión interesante sigue siendo: si necesita varias vistas de un documento, que debe ser la fuente y cuáles deberían ser los objetivos? Un mecanismo para generar un punto de vista específico sólo puede bajar de la estructura en el camino, así que las vistas que ofrece el más alto grado de estructura debe ser siempre la fuente. Por ejemplo, un documento bien estructurado es inherentemente más

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

135

Fuente única y Objetivos Múltiples

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 código HTML.

Del mismo modo, como comentarios de código fuente se asocian con las líneas de código, y por lo tanto ofrecer un mayor grado de estructura de HTML, comentarios de código fuente se extraen del código y en HTML, y no viceversa.

Discusión

generación automática de documentos no cambia la estructura de un documento, simplemente el formato del documento o de su diseño: el contenido permanece intacto. La condición previa para que esto funcione es que el contenido y el diseño no se mezclan en un documento, pero se separan correctamente. Por lo tanto, la viabilidad de la generación automática de documentos depende de la SEPARACIÓN DE CONTENIDO y el diseño

principio que se adopta para el documento de origen. Los mecanismos para la generación de documentos a menudo tienen que asumir que las fuentes están disponibles en un determinado lugar en el DOCUMENTO DE ARCHIVO. Por tanto, una estructura de archivo estable es la condición previa para este patrón para ser útil. Esto se puede lograr por lo permite REORGANIZACIÓN A PETICIÓN solamente.

Infraestructura y Organización Técnica

136

Importación por referencia Problema

¿Cómo pueden los diferentes documentos utilizar el mismo diagrama o tabla consistente?

Efectivo

La información 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 Introducción a la arquitectura, un documento de diseño y un concepto de uso.

Si incluimos estos elementos de información 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 generación de documentos en los que aparecen estos elementos no es una solución, ya que no es los documentos completos que son redundantes, sólo pequeños objetos en su interior.

Aún así, no hay necesidad de almacenar dichas piezas de información redundante. Todo lo que necesitamos son múltiples representaciones de la misma información.

Solución

Artefactos que deben aparecer en múltiples contextos pueden ser importados por referencia en los documentos que los incluyen.

Figura 40. Un gráfico referenciado por dos documentos

137

Importación por referencia

Esta técnica se ilustra en la Figura 40, y se puede caracterizar como sigue: •

Los diagramas, imágenes, tablas, etc. se almacenan en lugares apropiados.

•

Se incluyen en todos los documentos donde sea necesario el uso de la 'importación por referencia' mecanismo que la mayoría de los procesadores de texto ofrecen.

•

Si se cambia el elemento original, todas las instancias dentro de esos documentos se actualizan automáticamente la próxima vez que se abran los documentos.

Discusión

Esta técnica evita los problemas de mantenimiento asociados con la redundancia. Sin embargo, no se puede negar que hay varios inconvenientes asociados con la importación 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 automáticamente cuando cambia el artefacto, lo que conlleva el peligro de conflictivos información en el diagrama o tabla en una mano y el texto que lo rodea por el otro.

A continuación, si se necesitan artefactos especí fi cas en varios documentos, estos documentos se solapan, al menos hasta cierto punto. Esto puede ser una indicación de que dichos documentos no se enfocan correctamente, aunque no necesariamente. Si esto es el caso, se puede tratar de evitar la situación por completo mediante la consecución de más La información centrada, resultando en solapamientos más pequeñas.

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 más tiempo de lo que debería. Por otra parte, el uso de muchos artefactos que se hace referencia dentro de un documento es a menudo una construcción bastante frágil, como el DOCUMENTO DE ARCHIVO

en la que los elementos se almacenan podría someterse a una reorganización. Esto ayuda a poner en

práctica aquí REORGANIZACIÓN A PETICIÓN solamente, es decir, sólo para reorganizar el archivo cuando se solicita activamente por sus usuarios. Sin embargo, el mantenimiento de los documentos con referencias a elementos de información puede ser incómodo. Para solucionar el último problema, puede considerar la importación de artefactos en función, únicamente, siempre y cuando aplica su principal ventaja: el uso de importación 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.

Infraestructura y Organización Técnica

138

La separación de procesamiento e impresión Problema

¿Cómo 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 documentación del proyecto también deben ser capaces de leer e imprimirlo.

Sin embargo, otras personas no se supone a veces modificar la documentación, por lo que debe ser una forma de proporcionar una versión del documento que no permite el posterior procesamiento.

Además, 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 diseño y formato, ni deben el diseño y formato ser anulado por cierto, por ejemplo, la impresora Con fi guración.

Por desgracia, algunos procesadores de texto cambian documentos de forma automática el momento en que se abren. Peor aún, 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 página se convierte en una cuestión de pura casualidad.

Además, la apertura de un documento puede ser peligroso cuando el documento contiene macros que se ejecutan automáticamente, como macros pueden albergar virus. Preferiblemente, no hay macros deben ser ejecutados al leer o imprimir un documento.

Solución

Si un equipo elige para entregar la documentación del proyecto en un formato de impresión que está ampliamente disponible, todos los lectores son capaces de imprimir los documentos, independientemente de la plataforma que utilizan.

La clave de esta solución es la clara separación de formatos para el procesamiento de un documento en una mano y formatos de impresión en el otro. Los equipos deben tener cuidado para distribuir únicamente versiones de sus documentos en el formato de impresión siempre que no se espera que los receptores para procesar los documentos más.

139

plantillas de documentos

En detalle, los formatos de impresión deben cumplir con los siguientes requisitos:

•

formatos de impresión deben captar al máximo toda la información sobre el diseño y el formato de un documento. Esto incluye el uso de tipos de letra, la geometría de la página y así sucesivamente. El diseño de página del documento impreso debe ser parte del documento solo, y no debe depender de la infraestructura circundante.

Discusión

•

formatos de impresión no deben permitir su posterior procesamiento.

•

Idealmente, formatos de impresión no deben permitir la ejecución de macro tampoco.

•

Para asegurar la documentación está ampliamente disponible, el acceso a los formatos de impresión debe estar libre.

El PDF de descripción de páginas (formato de documento portátil) es el ejemplo más destacado de un formato de impresión que describe por completo y de forma inequívoca la página impresa. PDF es una excelente opción, ya que se puede leer con Adobe Acrobat Reader, una herramienta que está libremente disponible para múltiples plataformas.

PostScript es otro formato de impresión ú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 impresión tiene una influencia en la elección de un instrumento de documentación. Si usted es responsable de la creación de la infraestructura de la documentación, es posible que desee dar preferencia a las herramientas que directamente soportar los formatos de impresión, por ejemplo, herramientas que generan PDF. Tenga en cuenta, sin embargo, que ALGUNOS INSTRUMENTOS

debe ser su fi ciente para fines de documentación.

plantillas de documentos Problema

¿Cómo pueden todos los documentos del proyecto adquirir una estructura razonable y un buen diseño a bajo costo?

Efectivo

Hemos visto que el diseño y la materia formato. Un buen diseño hace que un documento más legible. Los documentos del proyecto deben cumplir con un cierto grado de estándares de formato.

Sin embargo, es ineficiente para permitir que los miembros del equipo se encargan de cosas como el diseño y el formato de forma individual. Todo el mundo vendría con su indicación

Infraestructura y Organización Técnica

140

soluciones viduales, por lo que no serían una apariencia consistente a través de los documentos del proyecto. Más importante aún, sería un desperdicio de recursos. En un proyecto ágil, asumiendo una actitud ágil, no todo el mundo tiene el tiempo para diseñar diseños de documentos. E incluso si varias personas se tomaron el tiempo, acabarían 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 diseño útil.

La reutilización de diseños de documentos bien diseñados suena como una buena idea. Sin embargo, no es sólo el diseño del documento que podemos reutilizar.

La mayoría de los proyectos tienen alguna experiencia con los contenidos típicos de documentos específicos. Ellos saben qué tipo de materiales debe entrar en un requisito específico fi cación, o en un documento de diseño, y así sucesivamente. Vale la pena la reutilización de esta experiencia, de modo que los miembros del equipo no necesita Re-inventar los elementos típicos de un documento tienen la intención de escribir.

Solución

plantillas de documentos, una vez que han sido diseñados adecuadamente, imponen su estructura y el diseño de todos los documentos que se producen de usarlos.

Casi todos los procesadores de texto permiten a los modelos que se utilizarán como base para nuevos documentos:

•

Una plantilla define el diseño de todos los documentos de un tipo específico. todo el conjunto de plantillas de documento define un diseño para ser heredado por los documentos del proyecto, como se muestra en la Figura 41. Además, las plantillas se pueden garantizar, al menos hasta cierto grado de general, un aspecto coherente en toda la documentación 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 más estructuración a los autores de las especificaciones individuales. Incluso puede incluir algún texto de la muestra como una especie de prototipo.

Idealmente, una persona o un pequeño grupo de personas, puede proporcionar todas las plantillas necesarias, y el resto del equipo no necesita preocuparse con cualquier diseño y formato. Las plantillas pueden incluso estar disponible para toda la organización, por lo que un proyecto sólo puede volver a utilizar el trabajo de proyectos anteriores.

141

plantillas de documentos

Figura 41. Las plantillas de documentos

Discusión

Para asegurarse de que las plantillas conducen a los documentos que son altamente legible y estéticamente agradable, las plantillas deben seguir los patrones tipográficos desde el capítulo 3, de lo contrario los errores tipográficos y diseños torpes se copian en muchos documentos.

A continuación, las plantillas deben ser fáciles de usar. A menudo, las plantillas relativamente simples hacen perfectamente bien. Hasta cierto grado, su simplicidad se puede medir por cómo una plantilla emplea el SEPARACIÓN DE CONTENIDO Y DISPOSICIÓN:

la plantilla normalmente formatos de párrafo de fi ne para los autores de los

documentos del proyecto para su uso. Un pequeño conjunto de formatos de párrafo, 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.

¿Cómo funciona exactamente plantillas puede proporcionar una estructura provisional para un documento? Una plantilla puede introducir marcadores de posición para los elementos estructurales descritos en el Capítulo 2, en particular para DIRECTRICES PARA LOS LECTORES,

para GLOSARIO y por una

HISTORIA DEL DOCUMENTO.

Las plantillas pueden hacer más que esto, sin embargo. Si usted decide tener una plantilla para cada documento de la CARTERA DE DOCUMENTACIÓN, puede configurar secciones para todos los temas que normalmente se tratan en estos documentos.

Infraestructura y Organización Técnica

142

Por último, para una colección 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 fácilmente, estos archivos deben someterse REORGANIZACIÓN A PETICIÓN

solamente.

pocas herramientas Problema

¿Cómo pueden los proyectos minimizar el esfuerzo dedicado a la introducción y el uso de herramientas de documentación?

Efectivo

Queremos producir documentación de alta calidad. herramientas adecuadas son necesarias para la producción, mantenimiento, impresión, almacenamiento y recuperación de documentos. Pero qué herramientas debemos elegir? Con este fin, hemos de recordar que la introducción 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 número de herramientas está implicado y, lo más importante, cuando las herramientas son complejas en uso. herramientas complejas se pueden convertir fácilmente a la carga en lugar de apoyar a los usuarios.

Para hacer la última declaración suene más positivo: podemos reducir el esfuerzo si se logra con menos y más simples herramientas. El esfuerzo asociado con herramientas depende también de las herramientas que los miembros del equipo han utilizado anteriormente. Las cosas son mucho más fáciles si un equipo puede contar con herramientas que muchos de los miembros del equipo han estado utilizando durante años. Por otra parte, hay una ventaja de costos en el uso de herramientas que están disponibles dentro de la organización, 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 documentación.

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 propósito. La mejor ventaja de costos no vale mucho cuando la herramienta no puede proporcionar el servicio que se necesita.

143

pocas herramientas

Solución

Casi todos los proyectos pueden manejar con un pequeño conjunto de herramientas de documentación.

La siguiente tabla muestra una lista de herramientas que pueda necesitar un proyecto.

Herramienta Procesador de textos

Propósito

Producir todos los textos en documentos de papel, incluyendo diagramas y tablas

editor HTML

Producir páginas Web, a menos que puedan ser generados

Cámara digital

Capturar la salida de talleres y debates pizarra

Hoja de cálculo

El trabajo en hojas de planificación

lector PDF

Leer e imprimir documentos listos para la impresora

navegador web

Leer documentos en línea

sitio web

Hacer que la documentación de los proyectos disponibles

gestión con fi

almacenar los documentos y las versiones del documento

guración Cuando tienes una selección de productos rentes cultades para cada categoría, los siguientes criterios pueden ayudar a tomar una decisión:

•

Calidad: herramientas deben ser fiables y fáciles de usar.

•

Disponibilidad: herramientas que están disponibles en la organización 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 documentación debe ser lo más simple posible. A veces los proyectos se inclinan a utilizar herramientas más complejas, tales como herramientas CASE que también apoyan la documentación. Antes de un proyecto toma una decisión en una herramienta de este tipo, sin embargo, tiene que ser capaz de explicar por qué es necesaria la herramienta, y cómo ayuda el equipo más que herramientas más simples podían.

Infraestructura y Organización Técnica

144

Discusión

El manifiesto ágil da preferencia a los seres humanos y la interacción de los procesos y las herramientas (como se cita en el libro de Alistair Cockburn (Cockburn 2001)). Esto no quiere decir que no hay ningún valor en las herramientas, pero nos recuerda que las herramientas deben servir a las personas y no al revés. Scott Ambler recomienda el uso de la herramientas más simples posibles, pero comenta que esto no siempre es lo mismo que herramientas sencillas. El grado apropiado de simplicidad depende del proyecto de REQUISITOS documentación individual.

Un ejemplo de una herramienta sencilla es la cámara digital, se menciona en la tabla de la página 143. Puede sorprender que la veas en la lista de herramientas de documentación, pero tiene mucho sentido. Una cámara digital es fácil de usar, y puede convertir los resultados de los debates de la pizarra en ESQUEMAS juiciosa. Esta técnica se ha sugerido en la literatura sobre el desarrollo ágil (Cockburn 2001, Ambler 2002).

En lo que se refiere a los procesadores de texto, asegúrese de que la herramienta que se utiliza es compatible con la generación de PDF, preferiblemente de una manera directa. Esta es la forma más fácil de lograr una SEPARACIÓN DE procesamiento y la impresión.

También dar preferencia a las herramientas que tienen un enfoque técnicamente

sólida a la SEPARACIÓN DE Contenido o de presentación por ejemplo, ofreciendo una forma sencilla para de fi ne formatos de párrafo.

Los cambios anotado Problema

¿Cómo pueden los autores evitar la confusión sobre los cambios que han hecho?

Efectivo

Mientras que un documento está todavía en desarrollo, los cambios se realizan con frecuencia. Esto no representa un problema, siempre y cuando sólo una persona está involucrada en la redacción del documento.

Documentación, sin embargo, puede ser un esfuerzo de colaboración. Varias personas pueden contribuir a un documento como co-autores. Co-autor de un documento es mucho más 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 solución, y la mayoría de los procesadores de texto ofrecen esta característica. Pero a medida que se hacen más cambios, el tamaño de los registros de cambios crece y crece, y después de un tiempo los registros se convierten en demasiado tiempo para ser útil.

145

Notificación sobre la actualización

Solución

Mientras que un documento se encuentra en desarrollo, los autores pueden utilizar las anotaciones automáticas para identificar aquellas partes del documento que han cambiado recientemente.

Los procesadores de texto ofrecen las siguientes técnicas para controlar los cambios realizados en un documento:

•

Cambio de barras en el margen exterior indican los párrafos 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 todavía puede ser visible, pero tachado.

•

Las anotaciones se pueden anexar al texto que dicen que los últimos modificados y cuándo.

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 sólo iban a estorbar el documento y destruir el diseño general, que no tendrían sentido para la mayoría de los lectores.

Discusión

Este patrón es de gran utilidad cuando un documento está escrito por los co-autores como un esfuerzo conjunto. Sin embargo, otro patrón recomienda que cada documento tiene UNO Autor responsable.

¿Es esto una contradicción? No, no lo es: la co-autoría de un documento es

perfectamente natural. El trabajo del autor responsable es asegurarse de que el documento está escrito según lo previsto, y si hay co-autores, que las contribuciones se integran sin problemas. Cambio bares y anotaciones están ahí para ayudar al autor responsable.

Notificación sobre la actualización Problema

¿Cómo se pueden prevenir los lectores del uso de versiones no actualizadas?

Efectivo

La información puede expirar, en particular, en un proyecto que todavía no se ha completado. se añaden nuevos documentos, los documentos existentes se actualizan. Normalmente queremos que nuestros colegas que lean las versiones más recientes de los documentos, ya que las versiones más recientes representan lo mejor de nuestro conocimiento. Pero, ¿cómo puede la gente sabe que hay un documento nuevo, o una nueva versión de un documento existente?

Infraestructura y Organización Técnica

146

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 línea para que puedan obtener nuevas versiones de forma automática. Dado que la impresión es el medio de elección para muchos documentos, la gente va a imprimir esos documentos de todos modos, y cambios serían 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 información? Información sobre actualizaciones debe ser lo suficientemente detallada para que las personas deciden si una nueva versión es relevante para ellos.

Sin embargo, no es una buena idea enviar un mensaje de correo electrónico que incluye la nueva versión de sí mismo. Esto sólo se aseguraría de que el documento se almacena de forma redundante muchas veces en los buzones de correo de los destinatarios.

Solución

Cada vez que hay un cambio significativo en un documento de proyecto, todos los lectores potenciales deben ser noti fi cado de la nueva versión. La noti fi cación debe explicar más o menos lo que se ha cambiado, pero no debe incluir el material actualizado en sí.

A menudo, el correo electrónico es el método de elección para notificar a los lectores. El catión notificada debe incluir la siguiente información:

Discusión

•

¿Qué documentos se han añadido o actualizado, y los números de versión pertinentes.

•

¿Por qué se hizo necesaria la nueva versión, y que el material es nuevo.

•

Un puntero a donde las nuevas versiones se pueden encontrar.

noti fi caciones se hacen necesarias como consecuencia de hacer CONTINUACIÓN DE DOCUMENTACIÓN, causado por la necesidad de desarrollar software y la documentación al mismo tiempo. El número de versión y la lista de los cambios propuestos en el catión fi NotI deben estar sincronizados con el HISTORIA DEL DOCUMENTO que aparece en el propio documento.

Antes de enviar la noti fi cación de una nueva versión de los lectores, el autor debe asegurarse de que la nueva versión se ha registrado en el DOCUMENTO DE ARCHIVO. La indicación del lugar donde la nueva versión se puede encontrar a continuación, es un puntero a la ubicación en el archivo donde se almacena la versión. Cuando se añaden nuevos documentos, informando a los lectores potenciales puede no ser suficiente - la documento horizontal

puede ser necesario actualizar también.

Reorganización a petición

147

Reorganización a petición Problema

¿Cómo se puede mantener la infraestructura de la documentación?

Efectivo

Una infraestructura estable es un factor clave para la documentación útil. Los usuarios esperan que los documentos que se almacenan en lugares específicos, esperan herramientas para trabajar de una manera particular y así sucesivamente. reorganización frecuente confunde a todo el mundo. Sin embargo, en algún momento de la reorganización de la infraestructura puede llegar a ser inevitable. Cuando un proyecto se inicia la infraestructura de documentación no puede ser completa. A medida que el proyecto evoluciona, los requisitos adicionales para desarrollar la infraestructura. Tal vez la jerarquía 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 reorganización representa una buena cantidad de esfuerzo. La adaptación de las vías de acceso, comprobando si las herramientas aún funcionan y así sucesivamente son tareas típicas que siguen reorganización. Esto hace que la reorganización bastante caro.

Además, una infraestructura casi nunca es perfecto; que casi siempre se puede mejorar. Este hecho por sí solo no justifica la reorganización. Hacer una infraestructura útil incluso mejor casi no vale la pena. La experiencia demuestra que, cuando la gestión de la documentación se ejecuta sin problemas, los usuarios sólo utilizan la infraestructura de documentación. Cuando la infraestructura de la documentación es problemático hasta el punto de que la reorganización se hace inevitable, los usuarios piden activamente cambios.

Solución

reorganización frecuente empeora las cosas, no mejor. Reorganización de la infraestructura de la documentación debe tener lugar sólo cuando es solicitado activamente por los miembros del equipo del proyecto. Reorganización 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 métodos existentes.

•

Los esfuerzos del proyecto suben y bajan en ciclos naturales, a veces de un año, a veces de medio año. Este período es un período de tiempo umbral durante el cual debe ser probable que una mayor reorganización no será necesario. En otras palabras, si usted está a cargo de la gestión de la documentación, que debe tomar las quejas de los usuarios acerca de la infraestructura de la documentación SERIAS

Infraestructura y Organización Técnica

148

ormente, pero no debe reaccionar de forma exagerada a los pequeños problemas que, si bien pueden existir, apenas son cruciales.

Discusión

La reorganización de la infraestructura de la documentación tiene una serie de consecuencias. Puede afectar a la plantillas de documentos

de dos maneras diferentes. En primer lugar, su ubicación 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 diseño coherente de los documentos existentes y futuros en riesgo.

Reorganización también influye en el uso de herramientas. En primer lugar, esto es cierto para un sistema de gestión con fi guración utilizada en el DOCUMENTO DE ARCHIVO, los cuales al menos las necesidades de sus vías de acceso ajustados. Pero quizás también la jerarquía de archivo se ve afectada: en este caso la reorganización debe preservar o recrear, la claridad y el equilibrio estructural del archivo.

En segundo lugar, la reorganización afecta a los mecanismos que generan automáticamente los documentos siguientes a la FUENTE ÚNICA Y OBJETIVOS DE MÚLTIPLES principio, así como los mecanismos para IMPORTACIONES POR REFERENCIA. Una vez más, las vías de acceso deben ser actualizados.

Programación y documentación - una analogía Hay una analogía interesante entre varios de los patrones en este capítulo y varios principios de programación. •

La creación de una DOCUMENTO PAISAJE e implementarla mediante un DOCUMENTO DE ARCHIVO se asemeja a los principios de las estructuras de datos y su representación física. El hecho de que se trata de dos modelos tiene sus raíces en la idea de que especi fi cación y aplicación deben estar separados.

•

los SEPARACIÓN DE Contenido y disposición contribuye a la disociación, que se suma a la flexibilidad de un documento. Esto es similar a la flexibilidad obtenida por un sistema de software a través de componentes de desacoplamiento después de la "separación de las preocupaciones de principio.

•

La discusión de formatos en el SEPARACIÓN DE procesamiento y la impresión es paralela a la discusión de formatos de intercambio de datos conocidos de ingeniería de software.

•

El uso de DOCUMENTO PLANTILLAS promueve la reutilización a través de un mecanismo similar a la herencia. plantillas de documentos proporcionan estructuras que se reutilizan muchas veces.

149

Informes de experiencia

•

Teniendo un SOLTERO FUENTE Y OBJETIVOS MÚLTIPLES así como la IMPORTACIONES POR REFERENCIA Evitar técnica (o al menos administrar) redundancia mediante la adición de un nivel de indirección. Una cierta pérdida 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 NOTIFICACIÓN EN ACTUALIZACIÓN se asemeja en gran medida arquitecturas de software basadas en eventos.

•

REORGANIZACIÓN EN SOLICITUD

discute el equilibrio entre la ventaja de una mejor organización y los costes de

reorganización - una discusión que se pueden encontrar en muchos proyectos de software. Estos principios son tan importantes en la documentación como en la ingeniería de software. A menudo la gente no se dará cuenta de su aplicación, y sólo se perderá ellos cuando no se aplican. Estos principios ayudarle a seguir un estilo de programación directa en una mano y una organización ágil de su documentación por el otro.

Informes de experiencia Veamos ahora en la infraestructura de la documentación de algunos de nuestros proyectos de la muestra. Veremos las diferentes técnicas que los proyectos utilizan para organizar su documentación, y también veremos los problemas que se enfrentan. Almacenamiento y

Si uno mira hacia atrás en la Figura 35 en la página 118, se puede ver lo que es un proyecto de

recuperación de

infraestructura mal organizada se parece. Entonces, ¿cómo un bien organizado documento horizontal ¿parece? La

documentos

figura 42 muestra cómo Proyecto Contentis organizó su documentación.

Contentis era bastante pequeño proyecto, por lo que el equipo optó por una solución muy simple para la organización de sus documentos. Los documentos se almacenan en el sistema de archivo, y control de versiones sólo consistieron en la adición de los números de versión de los nombres de los documentos. A pesar de, o quizás a causa de su simplicidad, esta solución funcionó muy bien.

En un proyecto más amplio, sin embargo, una solución más elaborada probablemente tiene sentido. Proyecto persistor también 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 gestión

con fi guración ya estaba en uso de versiones de módulos de software. Era lógico utilizar este sistema para la documentación del proyecto

Infraestructura y Organización Técnica

150

Las versiones PDF para

distribución

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 organización del sistema, lo que refleja la estructura dentro del sistema de gestión de configuración con fi, en el que las versiones antiguas no son visibles.

Navegador de proyectos se le ocurrió otra solución. Este proyecto utiliza una herramienta CASE todos modos, y almacena varios documentos de texto dentro de ella. Además, el proyecto también se sintió la necesidad de documentación HTML, para que puedan navegar a través de las descripciones de los diseños de componentes y la interfaz de especificaciones. Estos documentos HTML se colocaron en un proyecto WIKI, como se muestra en la Figura 44.

151

Informes de experiencia

formatos adecuados para el procesamiento y impresión

estructura clara

plantillas de proyecto disponibles integrado en la gestión de configuración con fi

Figura 43. Proyecto persistor: Documento paisaje en la parte superior de la documentación de gestión de con fi guración

152

Infraestructura y Organización Técnica

Figura 44. Navegador de proyectos: un documento horizontal basada en la Web

Por muy diferentes que estas soluciones son, todos ellos tienen en común que están bien organizados, clara y fácil de memorizar. Se obtiene una idea de la documento horizontal y usted sabe dónde buscar para cada documento. Todos estos ejemplos también hacen uso de MEDIA de fácil lectura. Tanto el Proyecto y el Proyecto persistor Contentis eligieron para producir documentos destinados a

153

Informes de experiencia

Proyecto persistor: una estructura de sistema le sencillo fi

La infraestructura para todos los archivos del proyecto se creó en cuanto el proyecto había comenzado. Esto incluye tanto los documentos del proyecto y código fuente. Estaba claro que el equipo se utilice un sistema de gestión con fi guración para el código, por lo que fue una decisión fácil 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 gestión de con fi guración 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 través de la generación 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 navegación a través de la documentación del proyecto, y por lo tanto suministra versiones en línea de algunos documentos. Proyecto Flexicar llegó a la misma conclusión. Este proyecto decidió proporcionar información específica en línea a petición del cliente. En ambos casos, el alto grado de referencialidad había llevado a documentos en línea como MEDIA de fácil lectura.

Flexicar proyecto: la generación de documentos de ejecución

Además de los documentos de diseño producidos, el cliente estaba interesado en la documentación de la aplicación real. JavaDoc era la herramienta perfecta para generar esta documentación sin ningún esfuerzo adicional. El equipo había suministrado los comentarios de código fuente siempre que sea necesario, y había seguido las directrices para los comentarios de Java desde el principio. Por lo tanto, un comentario de HTML para todas las clases se podría generar en ningún esfuerzo adicional.

La producción de

Esta discusión nos lleva a la cuestión de cómo se produjeron estos documentos en línea. Los documentos en

documentos

línea, tanto en Navegador de proyectos y en el proyecto Flexicar, incluidas la información que se originó en otro lugar. Esto no fue un problema, sin embargo, ya que en ambos casos las versiones en línea podría ser generados automáticamente. Navegador de proyectos generó sus documentos de forma automática a partir de una herramienta CASE. Proyecto Flexicar había seguido el principio de CODIGO-COMENTARIO

Infraestructura y Organización Técnica

154

PROXIMIDAD

y había suministrado ricos comentarios de código 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 cómo una herramienta puede ayudar en este caso. Una vez más, la información que se había hecho disponible en diferentes formatos, y que tiene una

FUENTE ÚNICA Y OBJETIVOS DE MÚLTIPLES

fue la clave para controlar la redundancia.

Proyecto Vista: generar una tabla a partir de un diagrama

El diagrama del paisaje de aplicación (Figura 7, página 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ó más penetración 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 descripción más detallada de las dependencias El equipo había identificado fi. Lo que se necesitaba era una lista de todas las dependencias, a la que se podría añadir más información y que permitió que las dependencias a clasificarse. El equipo decidió mantener una lista de todas las dependencias del sistema en una hoja de cálculo de Microsoft Excel. Esta hoja de cálculo era demasiado grande para ser mantenido de forma manual. Una persona escribió un pequeño script que extrae la información sobre las flechas que conectan las cajas en el diagrama de Visio y se transforma esta información en un formato que pudiera ser importado en la hoja de cálculo.

Este fue un mecanismo relativamente fácil que se implementó en unas pocas horas. Se trabajó e fi cientemente suficiente para permitir que la hoja de cálculo para actualizarse sobre una base casi diaria. Sin embargo, el Proyecto Navigator también tiene una advertencia para nosotros. Se tomó este proyecto un tiempo antes de que la infraestructura de la documentación estaba en marcha, lo que causó algunos problemas. Una vez que se estaba ejecutando, se reorganizó varias veces. La gente tenía que ajustar configuraciones fi herramienta Evaluación condicional más de una vez. En lugar de realizar una REORGANIZACIÓN A PETICIÓN, reorganizaciones innecesarios utilizan recursos que podrían haberse gastado mejor en otro lugar.

155

Informes de experiencia

Navegador de proyectos: la integración de diseño y documentación

El equipo realmente tenía sentimientos encontrados acerca de la documentación en este proyecto. La parte buena es que el proyecto siguió la estrategia de documentar todo lo más una vez. El cliente había sugerido el uso de mecanismos de generación 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 descripción, un diagrama de clases y la interfaz de especificación. Un marco de código para cada componente podría ser generada de forma automática, que incluía comentarios de código ce amarga por los métodos de interfaz.

•

Además, el cliente quería un documento de diseño pequeño para cada componente. Este documento también consistió en la descripción, el diagrama de clases y la interfaz especí fi cación, y se generó a partir del modelo de Rose.

•

Varios desarrolladores consideraron que las versiones en línea de los documentos de diseño eran muy útil, ya que utilizan estos componentes en su programación diaria. páginas HTML se generan automáticamente y se integran en la documentación general de la web del proyecto había 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 través de correo electrónico cada vez que se hizo una actualización disponible. La gente pronto tenían un montón de diferentes versiones de los documentos del proyecto en sus buzones, lo que llevó a varios conflictos en los que alguien utiliza una versión obsoleta.

En segundo lugar, se tomó un tiempo antes de que todos los mecanismos de generación estaban en funcionamiento. Hasta que esto se hizo, los componentes de Rose modelo y diseño 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 generación, se sometió a una reorganización frecuente. El equipo tuvo que usar diferentes mecanismos varias veces, lo que provocó una sobrecarga significativa.

Infraestructura y Organización Técnica

156

Del mismo modo, el Proyecto Paracelso se metió en problemas porque tomó demasiado tiempo para hacer la infraestructura de la documentación disponible. En este caso, el plantillas de documentos faltaban. Proyecto persistor muestra cómo este problema específico 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 diseño, no hay plantillas para estos documentos estaban disponibles debido a que la organización no proporcionó ninguna. El equipo tuvo la posibilidad de elegir el diseño de una plantilla por su propia cuenta o hacerlo sin una. Unas semanas después el proyecto, una persona se tomó el tiempo para configurar una plantilla de documento simple. En ese momento, sin embargo, todo el mundo ya había estado trabajando en sus documentos, que tenían una estructura bastante inconsistente y el diseño como resultado. La mayor parte de los documentos carecían 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 pequeño con sólo unos pocos documentos, por lo que el daño podría ser reparado rápidamente. Sin embargo, más tiempo de lo necesario se gastó en dar a esos documentos una estructura adecuada, por no hablar de formato y diseño. Había estado disponible la plantilla desde el principio, el doble de trabajo se podría haber evitado.

La conclusión que podemos sacar de estos ejemplos es que una infraestructura claro y efectivo es el mejor soporte técnico para la documentación 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 duplicación 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 reorganización frecuente y las infraestructuras están aplicando demasiado tarde en el proyecto.

Me gustaría concluir este informe experiencia con un ejemplo de lo fácil y eficaz puede ser soporte de herramientas. Entre otros, Alistair Cockburn y Scott Ambler recomiendan el uso de una cámara digital para documentar discusiones de diseño (Cockburn 2001, Ambler 2002): aquí es un ejemplo de proyecto

157

Informes de experiencia

Puertas abiertas. Es el resultado de una discusión pizarra que describe los procesos de implementación de un portal de Internet. Es un diagrama útil, y tardó sólo unos diez minutos para comprometerse a papel.

Figura 45. OpenDoors del proyecto: una instantánea cámara digital

5

Gestión y Calidad Garantía

El valor de la documentación sólo debe realizarse si la documentación está bien hecho. Si está mal hecho, será peor que no tener la documentación en absoluto.

Gerald M. Weinberg (Weinberg 1998)

Martin y Daniel, los programadores, y Laura, el director del proyecto, se sentaron alrededor de la cafetería, beber café y discutir los últimos resultados de fútbol. Laura dijo: "Oh, sí, una cosa me había olvidado en la reunión del proyecto - ¿Qué vamos a hacer con la documentación? 'Hmm ... que quieres decir, se supone que debemos hacer documentación?' 'Bueno, seguro que somos.' 'Ok, pero no podemos hacer que cuando hemos completado la próxima liberación de código? Tenemos absolutamente ningún tiempo para eso ahora.'

La conclusión a extraer de esta historia no es que no se debe planear la documentación de su proyecto en la cafetería. 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 conclusión de que se debe sacrificar la prueba antes de la liberación de código, pasar el tiempo en la documentación en su lugar, y entregar software que no ha sido probado.

Sin embargo, algo está mal aquí. Documentación, cuando se pone ese tipo de atención, probablemente ni siquiera vagamente cumplir con sus propósitos. Los documentos importantes es probable que sean desaparecidos, debido a que el director del proyecto y el equipo se olvidó de planear la documentación en el lugar primero. Están discutiendo la documentación entre otras reuniones y en realidad no lo toman en serio. Esta no es una estrategia que garantice que los esfuerzos de documentación están bien orientados. Los documentos

Gestión y Aseguramiento de la Calidad

160

Una actividad

consiste en

representa

distinta

DOCUMENTACIÓN

ESCRITURA Y REFLEXIÓN

CONTINUA

está coordinado por

requiere

es responsable para

responsable

REVISIÓN ANTES DE

ENTREGA

es responsable

AUTOR

para

conduce

se complementa

a

puede invitar a

por

al documento

Marketplace

CRÍTICA DE

es la

Información

CONSUMIDOR

condición previa

se extiende

a

hacia la toma de un

para

puede tomar

es la condición

en

puede invitar a

es un paso

previa para

REVISIÓN CULTURA

Una vista distante

Figura 46. Patrones para la gestión y control de calidad

GESTIÓN DEL CONOCIMIENTO

161

Una actividad distinta

que hacen que se escriba bien podría terminar como un montón de documentos 'de una sola escritura-lectura que nunca', por lo que no ofrecen ningún beneficio para los lectores.

La documentación no se produce automáticamente. Tienes que procurar que la documentación se lleva a cabo, y que se lleva a cabo de una manera que fi cios a las necesidades de su proyecto. La planificación no es necesario, y no debe, ser confundido con una metodología de peso pesado o incluso con una burocracia documentación. La planificación significa simplemente que tomar las decisiones necesarias. Cuando se decide sobre la documentación que necesita para equilibrar las fuerzas siguientes. Por un lado, la documentación 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 documentación que se gasta bien.

Un paso es identificar los materiales que realmente debería ir en documentos escritos. Esto ha sido muy discutido en el capítulo 1. El siguiente paso es identificar las personas que deben trabajar en la documentación. Gestión siempre debe ocuparse de las personas, y la gestión de la documentación no es una excepción. preferencias y habilidades personales de los miembros del equipo juegan un papel aquí. ¿Cómo se puede apoyar a los autores de la documentación del proyecto? Sin embargo, otro paso es involucrar a la garantía de calidad. Estos son temas los patrones en esta dirección capítulo.

Es hora de afirmar una vez más que este libro no presenta un método de documentación lista para ser utilizada por el director del proyecto. Los siguientes patrones no dicen quién debe escribir documentos especí fi cos y en qué momento. Más bien, ellos guían a configurar su propia forma de documentar los proyectos y montaje de experiencia en su organización. La Figura 46 proporciona una visión general.

Una actividad distinta Problema

¿Cómo se deben asignar recursos a las actividades de documentación?

Efectivo

La documentación puede ser importante para las etapas posteriores del proyecto o para el próximo proyecto. Si producimos documentación inexacta o ignorar por completo los requisitos de documentación, gran parte de la experiencia realizada por los miembros del equipo se perderán. El resultado es que tendremos que volver a inventar cosas más tarde, debido a la falta de documentación en el primer lugar.

Gestión y Aseguramiento de la Calidad

162

Sin embargo, la documentación se une recursos. Estos recursos no se pueden utilizar para otras cosas como la programación o la prueba. Es inútil discutir que la documentación que se debe dar tanto tiempo como sea posible. En primer lugar, la documentación no recibe automáticamente mejor cuando se pasa más tiempo en él. En segundo lugar, la documentación no siempre tiene por qué ser perfecto.

El desarrollo ágil sugiere que la documentación que ser suficiente, pero no más 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 documentación de los proyectos de software. Pasar tiempo en la documentación 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 documentación de un proyecto de consultoría, por ejemplo. Un fenómeno psicológico conocido hace que el asunto aún más di fi culto. Muchas personas son reacias a invertir en algo que sólo paga apagado más adelante. Este fenómeno es aún más marcada si sólo los demás 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 - más 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á ningún beneficio hasta más tarde.

Todo esto requiere una planificación, y la planificación debe tener en cuenta los bene fi cios que la documentación tiene para todo el proyecto, tanto ahora como en el futuro. Esto puede parecer obvio, pero también muchos proyectos han terminado con documentación insuficiente, ya que no tenía intención de documentación correctamente en el primer lugar.

Planificación, sin embargo, no se limita a la asignación de un presupuesto. Un presupuesto no vale mucho cuando un equipo está demasiado ocupado con otras actividades del proyecto - que siempre tienen mayor prioridad. Documentación necesita una razonable presupuesto y una

razonable prioridad, lo que sea 'razonable' significa en un proyecto específico.

163

Una actividad distinta

Solución

Cuando la documentación se considera una actividad de proyecto distinto, y no sólo el subproducto de codificación, se le puede asignar su propio presupuesto, la prioridad y el horario. La documentación se puede entonces compararse con otras actividades del proyecto.

La idea central es hacer que la asignación de recursos a la documentación

explícito, y abierto a la discusión, 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 documentación 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 documentación 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 próximo. actividades de documentación, si se toma en serio, se le dará una alta prioridad en algunos puntos y una prioridad inferior a los demás. El director del proyecto debe velar por que, en el transcurso del proyecto, la documentación recibe la prioridad que se necesita cuando se compara con otras actividades del proyecto.

•

El equipo también debe ponerse de acuerdo sobre un calendario para la documentación y fi jar una fecha de entrega para la próxima versión de cada documento necesario. Los clientes suelen esperar que la documentación 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 documentación.

Discusión

El tiempo y el presupuesto que necesita para la documentación depende claramente de la cantidad de documentación que es necesario. Dado que los proyectos tienen documentación individual REQUISITOS, el esfuerzo que tiene que gastar puede variar enormemente. La elección de los documentos necesarios de la CARTERA DE DOCUMENTACIÓN,

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 límites razonables.

La determinación de la cantidad necesaria de la documentación activa y explícitamente es una estrategia también se recomienda en la literatura sobre el desarrollo ágil. Alistair Cockburn no hace ninguna suposición acerca de qué o cuánto docu-

Gestión y Aseguramiento de la Calidad

164

mentación a necesidades del proyecto, pero se requiere un equipo de plantear y responder a esta pregunta, por ejemplo a través de un juego de planificación (Cockburn 2001). Hay más aspectos a la gestión de la documentación que el presupuesto y la prioridad. Otro tema es el de proporcionar un entorno que permite a los autores tratan de documentación como una mezcla de ESCRITURA y la reflexión. Por otra parte, una CULTURA REVISIÓN

necesita ser establecido que hace cumplir la REVISIÓN 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 documentación.

Un responsable Autor Problema

¿Cuántas personas deben ser responsables de un documento?

Efectivo

Si un gran número 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 sólo una persona, oa lo sumo un pequeño equipo, es responsable de cualquier tarea. Una idea es tener el trabajo a alguien en la documentación del proyecto a tiempo completo, ya que esta persona podría entonces concentrarse en el trabajo. Tal vez el proyecto, sin embargo, no puede prescindir de una persona durante el tiempo suficiente para escribir la documentación solo, o una sola persona no tiene suficiente conocimiento para hacerlo. Por otra parte, una persona que trabaja exclusivamente en la documentación no está involucrado en otras actividades del proyecto. Es más fácil de producir buena documentación cuando usted está involucrado activamente en un proyecto en lugar de simplemente observarlo. Esto sugiere que varias personas pueden tener que contribuir a la documentación.

A medida que las personas son diferentes, tienen diferentes intereses y habilidades. Algunos ingenieros de software no les gusta escribir documentación y prefieren las tareas más técnicas, mientras que otros que se le parezca. Si estamos interesados ​en la documentación de alta calidad, que debe asegurarse de que los autores son expertos y motivados. Cuál es el punto de obligar a alguien a hacer el trabajo que no está dispuesta a hacerlo?

Un responsable Autor

Solución

165

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 también 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, dicción y líneas de argumentación.

•

Se encargará de la revisión 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 documentación no sea demasiado grande en proporción a otras actividades del proyecto.

Discusión

Este modelo es una versión especial de un principio de gestión general. Entre sus patrones de reducción del riesgo de gestión de proyectos, Alistair Cockburn hace hincapié en que en un proyecto que debe haber exactamente una Propietario por entregable ( Cockburn

1998), de lo contrario podría funcionar a varias personas en la misma cosa, o tareas importantes podrían ser descuidada. Este principio se aplica a los documentos tanto como a todos los demás 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 CONTINUACIÓN DE DOCUMENTACIÓN,

y organizar una REVISIÓN antes de la entrega.

Gestión y Aseguramiento de la Calidad

166

Documentación continua Problema Efectivo

Cuando se debe escribir la documentación del proyecto?

Está claro que al comienzo de un proyecto no somos capaces de documentar todo lo que nos gustaría ver documentado por el final. Todavía no sabemos cuál es la arquitectura de software se verá así, por no hablar de los aspectos más detallados de diseño. De las cosas que podríamos 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 documentación hasta que el proyecto está terminado. Se necesita documentación sobre la comunicación con los clientes y entre los miembros del equipo. Tiene que estar disponible durante el proyecto.

Estos puntos sugieren que la documentación 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 diseño puede comenzar como un simple boceto y puede ser extendida como el diseño 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 información obsoleta. La información incorrecta puede ser la fuente de malentendidos graves, y por lo tanto puede hacer mucho daño. Peor aún, excesivamente largos lapsos de tiempo entre actualizaciones de la documentación crean el peligro de que los cambios no se están llevando a cabo en absoluto. En algún momento, la actualización de la documentación es fácil de olvidar. Esto claramente no es lo que queremos, ya que haría que la documentación inútil en el largo plazo debido a la inexactitud.

Todo esto sugiere que debemos ser bastante rápido con las actualizaciones. Si esperamos a que surjan problemas con los documentos obsoletos, hemos esperado demasiado tiempo - el daño ya está hecho.

Por otro lado, si la documentación se actualiza inmediatamente cada vez que un proyecto de detalle cambios, que tendrán que ser modi fi cado de manera casi continua. Esto es caro - la documentación requerirá mucha más atención de la necesaria. Por otra parte, la actualización de la documentación con demasiada frecuencia se asegura de que la mayoría de las veces no hay documentación estable está disponible. Esto está en conflicto con nuestro deseo de tener útil documentación, aunque incompleta, desde el inicio del proyecto.

Documentación continua

Solución

167

La documentación 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 documentación exige documentación que se actualiza a intervalos regulares. Qué plazo puede suponer para éstos r intervalos ERIÓDICAS depende del proyecto individual: •

A menudo es una buena idea para actualizar la documentación con las nuevas versiones de software, manteniendo de este modo la escala de tiempo de versiones de software y documentación en sincronía.

•

La frecuencia de las actualizaciones depende también del tipo de documento. documentos más generales, tales como descripciones de la arquitectura, son más estables y tienen un menor número de cambios que, por ejemplo, una interfaz específica de cationes, que puede cambiar de un día en un proyecto ocupado.

•

Las actualizaciones pueden ser más o menos urgente. Un documento importante, que se utiliza sobre una base del día a día, debe actualizarse rápidamente cuando su objeto ha cambiado. Un documento diferente puede ser utilizado con menor frecuencia: la actualización de este documento no es tan urgente y tal vez puede esperar.

La documentación existente, quizá en su estado intermedio, debe ponerse a disposición de todos los miembros del equipo, para que puedan utilizarlo como avanza el proyecto.

Discusión

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 más corto para que la entrega de software no se ralentiza. Un par de semanas también suena como un buen promedio marco de tiempo para la actualización de los documentos, aunque más corta, así como los intervalos más largos puede tener sentido. Entre las actualizaciones, la documentación 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 técnica sencilla que Charles Weir sugiere entre sus Las pautas de diseño en equipo: todos los miembros del equipo pueden tener una copia impresa de la documentación y hacer Correcciones (adhoc Weir 1997) hasta la próxima versión se distribuye al equipo. Afortunadamente, muchos de los documentos que se someten a cambios rápidos son los que la gente utiliza para buscar información - documentos que normalmente se presentan

Gestión y Aseguramiento de la Calidad

168

en línea (ver De fácil 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 documentación continua, la documentación 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 actualización y el Un autor RESPONSABLE debe asegurarse de que se cumple la frecuencia de actualización.

Debido a que la documentación está escrita y utilizar mientras avanza el proyecto, que está abierto a la CULTURA REVISIÓN

es de esperar que el proyecto ha establecido. Este es un problema doble. En primer lugar, escribir

documentación puede dar una idea del software, como ESCRITURA Y REFLEXIÓN puede ir de la mano. Por ejemplo, al describir un diseño, de manera implícita que validar, tanto como lo hace cuando se lo explicas a los demás. De esta manera, la documentación puede contribuir a la calidad del software. En segundo lugar, como la documentación que se utiliza durante el proyecto, los miembros del equipo pueden dar información sobre la calidad de la misma documentación.

La escritura y la reflexión Problema

¿Cómo pueden documentación y otras actividades del proyecto estimular el uno al otro?

Efectivo

Las buenas ideas necesitan tiempo. La documentación 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 reflexión durante la escritura.

Esto es aún más cierto para la documentación en condiciones de cambios rápidos. Evolving proyectos suelen ir de la mano con el crecimiento gradual de la documentación, que requiere autores para reflexionar sobre los cambios y adaptaciones que necesitan para tomar.

Los autores no sólo se re fl ejan en los documentos que escriben, sino que también reflejan en la materia. La documentación es un medio importante de validación. Usted puede obtener información, por ejemplo, en un diseño de software, mientras que documenta, y observe lo que es imperfecta o incompleta. Escribir documentación proporciona información sobre lo que se está documentada.

169

La escritura y la reflexión

En algunos casos, la reflexión puede ser el propósito 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 través, es crucial tomar el tiempo necesario para las nuevas ideas y la reflexión.

El tiempo no es todo, sin embargo. Los autores también 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 documentación, un poco de paz y tranquilidad puede hacer mucho bien. La importancia del trabajo en equipo pesar de ello, una habitación con muchas personas alrededor no es un entorno que permite a una persona a concentrarse en la escritura.

Solución

Para sacar el máximo partido de la documentación, los miembros del equipo tienen que pasar tiempo en la escritura real, así como en la reflexión sobre lo que han escrito, preferiblemente en un entorno tranquilo.

Esto se puede dividir en los siguientes consejos concretos: •

materiales y estructuración que el material consiste en la recogida de la creatividad. Es casi imposible escribir un documento perfecto directamente hacia afuera. La elección del material y la definición de una estructura inicial documento tienen que ser objeto de reflexión. 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 documentación de problemas e inconsistencias. Si se observa que las partes de la documentación son problemáticos, esto puede sugerir que es el sujeto de la documentación que es en sí misma problemática. De esta manera se obtiene información sobre el proyecto en sí.

•

La mayoría de la gente no puede reflejar inmediatamente después de lo que acabo de escribir.

-

que necesitan para ganar un poco de distancia. Por lo tanto, usted debe dejar ningún proceso de escritura se

extienden sobre un período 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 más tiempo en la documentación. El plan justo para tomar un descanso, y para hacer otras cosas en el medio, antes de completar un documento.

Gestión y Aseguramiento de la Calidad

170

•

A los efectos de documentación, 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 documentación puede convertirse en un medio de validación. En un estilo similar al de diagramas de secuencia UML, con el tiempo fl debido de arriba a abajo, el diagrama muestra cómo la los procesos de documentación de diseño y evolucionan para producir sus resultados final. Documentación, que consiste en la escritura y la reflexión, se lleva a cabo a intervalos regulares, y materiales de retroalimentación para el proceso de diseño, que continúa sin interrupción.

Discusión

En la mayoría de los proyectos que es conveniente reservar marcos de tiempo regulares para la documentación y reflexión. Una idea es pasar cuatro días a la semana, el diseño, codificación, teniendo reuniones y discusiones, tal vez trabajando en las instalaciones del cliente, sino para reservar un día por semana para la documentación y reflexión en un ambiente más tranquilo. una política de este tipo permite CONTINUACIÓN DE DOCUMENTACIÓN.

Dado que la documentación es Una actividad distinta, su presupuesto y la prioridad puede ser alto o bajo, dependiendo del proyecto, por lo que la regla de "cuatro días frente a un solo día de no siempre podrían ser apropiadas. En muchos casos, sin embargo, representa un equilibrio entre definen el desarrollo de software, por un lado, y la documentación y reflexión sobre la otra.

Por último, la necesidad de un entorno tranquilo no significa que usted debe escribir la documentación de forma aislada. Sólo una adecuada CULTURA REVISIÓN permite llevar a cabo una REVISIÓN antes de la entrega entre el equipo, o una CRÍTICA DE CONSUMIDOR,

que le da la información necesaria de los demás.

revisión Cultura Problema

¿Cómo 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 revisión, 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 crítica, 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 pequeños y brillantes de los críticos, o puede ser que tenga miedo de la extra de

171

revisión Cultura

reflexión

escritura

de entrada para la

sujetos a La reflexión

documentación

validación

sujetos a La reflexión

validación

de entrada para la documentación documentos para la documentación

final de diseño

fi nal de entrada de

Figura 47. Documentación como un medio de diseño de validación

esfuerzo de incorporar la retroalimentación 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 mayoría de la gente acepta la crítica mucho mejor si está claro que la crítica está destinada a ayudar, no para ponerlos abajo. Para lograr este objetivo, una revisión no debe ser restringida a la retroalimentación negativa, sino que también debe tener efectos positivos

Gestión y Aseguramiento de la Calidad

172

comentarios que hacer, y la revisión deben ofrecer sugerencias concretas de mejora, junto con sus observaciones críticas (Coplien 2000). Además de este problema psicológico, también hay un punto de vista práctico que sugiere que la revisión debe incluir la retroalimentación tanto positiva como negativa. Los autores son a veces inseguro sobre si mantener o reemplazar el material específico. Sugerencias para cualquiera de los enfoques - mantener o reemplazar - pueden ser útiles. Pero cuando una revisión no menciona lo que es bueno, el autor podría terminar material que realmente debería haber sido dejado como estaba reemplazando. Una revisión de todo negativo deja el autor en la oscuridad y no es muy útil.

Solución

La documentación puede bene fi cio muchos de los comentarios, siempre una cultura opinión se ha establecido en la cual ambos autores y los colaboradores se sientan cómodos.

Una cultura crítica positiva requiere lo siguiente: •

Los miembros del equipo deben estar dispuestos a discutir el material y proporcionar información 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 críticos, los revisores deben hacer sugerencias concretas para la mejora siempre que sea posible.

•

Los miembros del equipo que ofrecen retroalimentación deben recibir el reconocimiento y el crédito que se merecen.

•

Los autores deben estar dispuestos a aceptar la retroalimentación, 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 espíritu 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 están en el mismo barco. Esto no sólo es cierto para la documentación, es cierto para todas las tareas del proyecto, y la documentación no es una excepción.

173

revisión Cultura

Discusión

cultura opinión, el trabajo en equipo y, en general, ha sido objeto de mucha atención en la literatura. Varios libros que ponen el énfasis en temas humanos en la computación reconocen la importancia del trabajo en equipo en todos los aspectos del desarrollo de software. Gerald Weinberg, en su libro sobre La

psicología de la programación informática, habla de la programación 'ego-menos' (Weinberg, 1998). Frederick Brooks, en El mes laboral mítico, ( Brooks 1995), y Tom DeMarco y Timothy Lister peopleware ( DeMarco Lister 1987), también proporcionan un montón de penetración en el trabajo en equipo.

El trabajo en equipo, revisión, reflexión y retroalimentación también 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 cómo pueden ser más eficaces, a continuación, ajustar y adaptar su comportamiento en consecuencia (Cockburn 2001). Varios métodos ágiles más 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 reflexión pueden ser como, y da muchos ejemplos (Kerth 2001). Neil Harrison Los patrones de organización para equipos ( Harrison 1996) hacen hincapié en la importancia del espíritu de equipo para todas las actividades del equipo. UN La unidad de propósito - compartiendo un objetivo común - es crucial para un equipo para trabajar bien juntos. En su libro Talleres de escritura, Richard Gabriel describe una cultura reseña que sea muy común entre los autores de la prosa y la poesía, y que ha sido adoptado por la comunidad para la revisión de los patrones de patrones de software (Gabriel, 2002). Un taller de escritores es un evento específicamente diseñado para permitir a los autores dan unos a otros retroalimentación intensa en su trabajo. Jim Coplien ha descrito esta cultura en su opinión Idioma patrón para

talleres de escritura ( Coplien 2000). Afirma que los autores y los colaboradores deben formar una Comunidad de confianza en el que los comentarios críticos son útiles, en lugar de causar irritación. Jim Coplien pide que, para la crítica sea útil en la práctica, concreta Sugerencias para mejorar se ofrece con cada comentario crítico. También hace hincapié en la importancia de tener Comentarios positivos En primer lugar, ya que por razones psicológicas, comentarios críticos son más fácilmente aceptadas después se ha proporcionado retroalimentación positiva.

Ninguna de estas ideas sobre el trabajo en equipo se aplica exclusivamente a la documentación. La mayoría de las ideas se aplican al desarrollo de software en general, mientras que la

Gestión y Aseguramiento de la Calidad

174

ideas para los talleres de escritura son, dentro del contexto de la ingeniería de software, dirigidos principalmente hacia la discusión de los patrones de software. Sin embargo, lo que todas las personas mencionadas anteriormente tenía en mente cuando escribió sobre el trabajo en equipo fue capacitar a los equipos a colaborar en un objetivo común. Esto es algo de lo que la documentación puede también pro fi t.

Revisión Antes de entrega Problema

¿Cómo pueden los autores recibir la retroalimentación adecuada en el momento adecuado?

Efectivo

Sabemos que los documentos deben ser revisados. Sin embargo, también sabemos que los exámenes utilizan recursos, y que los comentarios innecesarios deben ser evitados por razones económicas. ¿En qué medida son necesarios exámenes? 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 revisión.

A continuación, 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 someterán a cambio. Es perfectamente aceptable para hacer circular dichos documentos entre colegas que entienden que son los documentos preliminares. Fi ciales de revisión para las versiones preliminares no tienen sentido. No obstante, los comentarios sobre una versión preliminar puede ayudar a formar el alcance y la estructura general de un documento desde el principio.

En algún momento, sin embargo, son los documentos o fi cialmente distribuida - tal vez sólo en el equipo, o tal vez para el cliente, con una versión de software. Estos documentos deben cumplir con los estándares más altos de calidad.

Solución

Las primeras críticas 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 revisión es obligatoria. Sólo el autor puede decidir en qué medida temprana o intermedia comentarios son útiles. En la mayoría de los casos una revisión informal es su fi ciente para dar el autor retroalimentación temprana.

El examen final no es tema de debate. Como regla general, ningún documento debe ser puesto en libertad a los lectores no involucrados hasta que haya pasado un examen final.

175

Crítica de consumidor

Esta revisión debería tener lugar mucho antes de la fecha prevista de la distribución del documento, para dar tiempo a las revisiones, y debe responder a las siguientes preguntas:

Discusión

•

¿El documento cumple con sus objetivos, y será de utilidad para los lectores?

•

Es el documento técnicamente precisa, y tampoco proporciona el nivel adecuado de detalle técnico?

•

Es la estructura y organización general ¿verdad?

•

¿El documento proporciona suficientes ejemplos para ser comprensible?

•

¿Qué pasa con el diseño y el lenguaje?

Los comentarios no ocurren automáticamente. Es responsabilidad del documento de UNO autor responsable

para asegurarse de que los exámenes 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 sólo tiene que procurar que las votaciones se incorpora, pero también es libre de decidir cómo las votaciones se incorpora. La necesidad de este patrón se deriva en gran parte de la idea de CONTINUACIÓN DE DOCUMENTACIÓN. 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 también es el momento de planificar la revisión final.

Los comentarios se refieren principalmente a los contenidos de un documento. Además, los colaboradores pueden comprobar la calidad de la presentación. Especialmente, se pueden examinar qué tan bien un documento aborda la A quién va destinado, lo bien que se presenta CENTRADO INFORMACIÓN,

y la calidad de Ejemplos realista.

Crítica de consumidor Problema

¿Cómo puede utilizar un equipo de documentación para aumentar la implicación 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 documentación no es una excepción. Los equipos son, por tanto, inclinados a progresar rápidamente, por lo que tienen resultados que pueden ofrecer. Sin embargo, la implicación del cliente es necesario. En primer lugar, el proyecto

Gestión y Aseguramiento de la Calidad

176

actores están interesados ​en cómo está progresando el proyecto, y su participación es una manera de mantenerlos informados. En segundo lugar, el cliente es informado con claridad, especialmente en el dominio de la aplicación, y puede contribuir mucho a hacer el proyecto más exitoso.

La documentación es un área donde los clientes pueden estar involucrados. La entrega de la documentación a los grupos de interés es una forma de mostrarles hacia dónde se dirige el proyecto. Por otro lado, el cliente también puede proporcionar información valiosa sobre la documentación.

Todo esto se puede resumir diciendo que la mejor es la colaboración con el cliente, mejor son las posibilidades de éxito del proyecto. Solución

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 añadir a la formación de equipos y la integración.

Las siguientes pautas ayudan a hacer revisión 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 colección de materias primas en un documento para usted.

Una revisión 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 común.

Discusión

Colaboración con el cliente es uno de los valores fundamentales del manifiesto ágil. Se ha enfatizado mucho en la literatura sobre el desarrollo ágil, y más generalmente en la literatura sobre el trabajo en equipo eficaz de los proyectos. Por ejemplo, Jim Coplien, en su Desarrollo generativo-Proceso lengua

del patrón ( Coplien 1995), recomienda que los proyectos Atraer a los clientes, especialmente, aunque no exclusivamente, para fines de control de calidad. En su Patrones de interacción 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 colaboración con el cliente desee.

177

Una vista distante

Para una revisión del cliente para trabajar sin problemas, el equipo y el cliente tienen que establecer una CULTURA REVISIÓN

en el que dichas revisiones se considera normal, y en la que ningún miembro del equipo tiene

razones para sentirse ofendido por las críticas. El cliente debe reconocer la necesidad del equipo para la retroalimentación, y no debe culpar al equipo por no ser expertos en el dominio de aplicación. El cliente debe entender que la solicitud de revisión es una manera de asegurar la calidad de los resultados del proyecto.

Una vista distante Problema

¿Cómo pueden los autores obtengan retroalimentación imparcial?

Efectivo

Los colaboradores que están muy familiarizados con un documento en revisión son propensos a tener una visión algo sesgada. Puede ser que tome un montón de cosas por sentado que podrían ser interrogados por un revisor imparcial, y por lo tanto pueden no llegar a una evaluación fiable.

Este suele ser el caso cuando los miembros del equipo actúan como colaboradores. En general, se definen para tener la documentación del proyecto los miembros del equipo de revisión, 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 todavía puede ser sofisticado para los no expertos.

Por otra parte, los documentos del proyecto son a menudo revisados ​por personas con formación técnica. Estos revisores tienden a centrarse en el contenido técnico de un documento pero pasan por alto los problemas de presentación. Sin embargo, la calidad de la presentación también merece atención.

Solución

Los autores pueden obtener retroalimentación imparcial de los colaboradores que están interesados ​en el tema y que por lo general tienen conocimiento en el campo, pero que no están involucrados en el trabajo real se describe en el documento. Los buenos candidatos para una revisión lejana visión son:

•

Alguien desde fuera del equipo que esté familiarizado con el dominio de aplicación.

•

El cliente, que a menudo puede tomar una perspectiva ligeramente diferente.

•

En menor grado, un crítico desde el interior del equipo con un nivel educativo diferente.

Gestión y Aseguramiento de la Calidad

178

Normalmente estas personas no van a centrarse en los detalles técnicos en sus opiniones - y, de hecho, en realidad no debería. Más 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.

Discusión

En realidad hay dos tipos de comentarios que se complementan entre sí. Para los beneficios de una CULTURA REVISIÓN

materializarse plenamente, es necesaria la retroalimentación a diferentes niveles. Por un lado,

colegas cercanos que están familiarizados con el material presentado puede proporcionar comentarios útiles en un nivel más técnico. Por otro lado, la gente de fuera del equipo, tal vez el A quién va destinado, puede tener una visión lejana y proporcionar valiosos comentarios de alto nivel. Si es el cliente que toma la vista lejana, mantener los lineamientos para una CRÍTICA DE CONSUMIDOR en mente.

La recomendación de poner a alguien de fuera del equipo se encuentra comúnmente en la literatura. En su Desarrollo generativo-Proceso lengua del patrón ( Coplien 1995), Jim Coplien se ocupa de la cuestión de las revisiones de diseño. Se sugiere la contratación de una analista mercenaria desde fuera del equipo que es un experto en el dominio y que puede proporcionar retroalimentación. Este es un principio importante, no sólo para las revisiones de diseño, sino también los exámenes de proyectos de documentación. En el Creador-Crítico patrón de la Las pautas de diseño de equipos

(Weir, 1997), Charles Weir explica que el conocimiento detallado del dominio de aplicación es un requisito importante para un revisor. También recomienda que los colaboradores no estar involucrados en el trabajo que se examina.

Por último, este modelo también corresponde a una observación descrito en Neil Harrison Los

patrones de organización 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 más homogéneas, ya que los miembros del equipo se complementan entre sí. En lo que se refiere al proceso de revisión, la mejor retroalimentación se puede esperar de los colaboradores de distintos orígenes, tanto el uno al otro y al autor.

179

información del mercado

información del mercado Problema

¿Cómo se pueden prevenir buenos documentos de ir tristemente inadvertido?

Efectivo

La producción 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 ningún punto en la realización de un documento, poniéndolo en los archivos ya la espera de otros miembros del equipo que vienen a través de ella. Esta sería la estrategia correcta sólo 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 comunicación entre el equipo. Esto significa que tenemos que abordar activamente los miembros del equipo y hacerles saber que no es un documento que les podría ayudar con su trabajo.

Sí, hay opciones técnicas para hacer documentos fácilmente disponibles, y hay maneras de técnicas para distribuir documentos entre un equipo. Es definir de usar estas posibilidades, y son el primer paso para hacer la documentación de un medio eficaz de comunicación. Pero puede tomar un importante segundo paso al atender directamente los lectores previstos.

Solución

Documentos ganan más atención si los presuntos lectores están 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 disposición:

•

Se puede mencionar el documento en una reunión de equipo, dará una breve introducción 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 tablón de anuncios del proyecto.

Puede enviar un mensaje de correo electrónico breve al equipo en el que se explica el propósito del documento y dónde se puede encontrar. En cualquier caso, la documentación per fi cios en gran medida de una atmósfera en la que la información se intercambia libremente, y en el que las personas que los demás sepan de cualquier documento que les podría ayudar.

Discusión

Este patrón parece similar a la idea de dejar que sus colegas sabe de una nueva versión a través de una NOTIFICACIÓN EN ACTUALIZACIÓN. El énfasis de este patrón,

Gestión y Aseguramiento de la Calidad

180

Sin embargo, no es en ningún tipo de soporte técnico, sino más bien en las personas toman actitud hacia la documentación. Este patrón nos recuerda que, cuando hemos completado un documento, se supone que debemos llevar el documento a la OBJETIVO Lectores.

Una de las opciones de implementación para este patrón - fijando un documento importante para el tablón de anuncios del proyecto - está estrechamente relacionado con lo que Alistair Cockburn llama una 'información del radiador'. En Desarrollo Ágil de Software, sugiere que cada proyecto utiliza un radiador de información que muestra información en un lugar donde los transeúntes pueden verlo (Cockburn 2001). Si un equipo se utiliza para la comunicación electrónica, también 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 adopción de una cultura de intercambio de información gratuita en proyectos allana el camino para una actitud ágil hacia el tratamiento de la información más allá de los proyectos. Si consideramos la documentación como algo que se distribuye de forma activa, nos encontramos con la condición previa para el éxito, en toda la organización Gestión del conocimiento.

Gestión del conocimiento Problema

¿Cómo pueden los proyectos futuros bene fi cio de un proyecto exitoso?

Efectivo

No hay dos proyectos iguales. Sin embargo, los proyectos tienen cosas en común. Hay analogías y similitudes. Todos hemos estado en situaciones en las que tuvimos que encontrar una solución a un problema, muy consciente de que los demás deben haber resuelto un problema similar antes. Si tan sólo pudiéramos aprender sobre su solución, podríamos 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 sólo si se pone a disposición dentro de la organización. La documentación 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 documentación 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 información esté disponible.

181

Gestión del conocimiento

Solución

Sólo cuando la documentación del proyecto se pone a disposición de toda la organización hacer proyectos de futuro tienen la oportunidad de aprovechar la experiencia adquirida.

Esto tiene tanto una técnica y un aspecto cultural:

•

Hacer la documentación disponible requiere algún tipo de sistema de gestión del conocimiento, como se ilustra en la Figura 48. Tal vez esto es una guía accesible al público, tal vez es una intranet.

proyecto E

proyecto D

proyecto C

proyecto B

Un proyecto

base de conocimientos

Figura 48. Extracción de conocimiento y transmitirla

Gestión y Aseguramiento de la Calidad

182

•

El aspecto cultural es más importante. El uso de documentación para la gestión del conocimiento puede ser útil sólo en una cultura que anima a la gente a compartir sus experiencias. La comunicación informal juega un papel muy importante aquí. Como un miembro del proyecto, informe a los colegas que existe la documentación. 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.

Discusión

Técnicamente, lo que sugiere que este patrón es la integración del proyecto de DOCUMENTO PAISAJE en un paisaje de documentos que son relevantes para toda la organización. Si utiliza una intranet esto es particularmente fácil, convirtiendo su proyecto WIKI en una casa en WIKI.

Aquí es donde se cierra el ciclo de documentación. Usted ha estado ocupado haciendo CONTINUO DOCUMENTACIÓN

a través de su proyecto, que ha pasado por etapas de Y ESCRITURA REFLEXIÓN,

y el CULTURA REVISIÓN que ha permitido a fi nes de los conocimientos de sus colegas. Ahora la experiencia que ha adquirido puede ser útil para los demás. 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 DISEÑO RAZÓN FUNDAMENTAL.

En este punto, se ha producido una serie de documentos en su proyecto. No debería haber demasiados de ellos. Los patrones anteriores de este libro le han guiado a un enfoque en los temas correctos, y para hacer la documentación bien organizada y ligero. Ahora usted y otros pueden bene fi ciarse de trabajo que se hizo. Esta es la idea de la documentación ágil.

Informes de experiencia Me gustaría concluir este capítulo con mediante el examen de los procesos de documentación en varios proyectos de ejemplo, y cómo estos procesos cumplió o no cumplió con los patrones en este capítulo.

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 más, 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.

183

Informes de experiencia

Proyecto persistor da un buen ejemplo de lo que es un proceso de documentación de peso ligero puede ser similar. El equipo era consciente de que un cierto grado de documentación fue crucial para el éxito del proyecto, considerado como la documentación UN ACTIVIDAD DISTINCT, e incluido las tareas de documentación en la lista de las actividades del proyecto, como se muestra en la Figura 50.

30%

15 %

50%

15 %

Documentación Especificación

Diseño

Codificación

pruebas

Figura 49. Proyecto persistor: se espera presupuesto de documentación en un proyecto de desarrollo

Paquetes de trabajo para la liberación 5.0

No.

Paquete

1

funcionalidad

Presupuesto Prioridad Observación Responsable

1.1 Manual de desbloqueo

2

do

RS

verificación de tipos 1.2 API

5

segundo

Alaska

1.3

La mejora de los códigos de error

2

pruebas

Lanzamiento

claro si realmente se necesita 5.0

5.0

UN

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

Actuación 20

segundo

RS

5.0 o posterior

mecanismos de ajuste 3.1 Rendimiento 4

Documentación

4.1 concepto de uso: describir una funcionalidad adicional 2

UN

Arkansas

5.0

concepto 4.2 Uso: añadir ejemplo para el modelo de estado 1

UN

Arkansas

5.0

4.3 Concepto de diseño: actualizaciones 5

5

do

5

UN

5.0 o posterior

Entrenamiento

5.1 Taller 2000-05-25

Arkansas

Figura 50. Proyecto persistor: hoja de planificación del proyecto, incluyendo tareas de documentación

Gestión y Aseguramiento de la Calidad

184

Proyecto persistor: documentación 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 documentación se trató en estas reuniones, al igual que todas las demás tareas del proyecto. Al principio, el proyecto tenía de fi nen ciertos documentos que tenían que ser por escrito, y se había decidido sobre algunos documentos adicionales más adelante. Durante las reuniones regulares del equipo comprueba el estado de los documentos y lo que aún había que hacer.

Los documentos se consideraron artefactos del proyecto al igual que el código, casos de prueba y así sucesivamente. Para cada documento de una persona que estaba a cargo. Cada documento contó con un presupuesto que podría 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 planificación del proyecto.

¿Cómo manejar el equipo para estimar el esfuerzo que era necesario para la documentación? Esto se realiza principalmente sobre la base de la experiencia. La figura 49 muestra cómo, en esta organización, 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 también cómo gran parte del esfuerzo que el equipo espera que entre en la documentación - proporcionalmente más en la fase de especi fi cación, pero disminuye a partir de entonces. El porcentaje de la documentación puede parecer bastante alto, y de hecho es más pequeña 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 más grande para la documentación.

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 cómo aplicar el marco en casos prácticos los obligaron a reflexionar sobre cuestiones que habían pasado desapercibidos en las discusiones de diseño, y que tal vez habían dado por sentado.

Por desgracia, el documento de diseño no se manejó tan bien. El documento de diseño perdió la atención 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 sentía responsable del documento, por lo que las actualizaciones necesarias que nunca se hicieron. Diferentes personas añaden material, pero de forma no coordinada. El documento terminó inconsistentes y anticuado, proporcionando algunas ideas de diseño pero que carecen de la motivación detrás del diseño y las ventajas y desventajas de los diferentes enfoques que se habían examinado. Este documento no sirvió su propósito muy bien.

185

Informes de experiencia

El equipo decidió que la documentación era necesaria y ajustar sus decisiones con regularidad. En general, este proceso funcionó bastante bien. La documentación en su totalidad se descompone en paquetes manejables, y cada documento tenido UNO autor responsable y un plazo que permita una REVISIÓN antes de la entrega.

La documentación del proyecto persistor enfrenta un gran problema, sin embargo. A pesar de que había comenzado como CONTINUO DOCUMENTACIÓN, cambios a la documentación más tarde fueron descuidados cuando los plazos dibujaron la actividad más y animado situado en. Como consecuencia de ello, la exactitud de los documentos sufrió. En lugar de describir cómo el diseño del marco había evolucionado y por qué, todo el documento de diseño del mencionado fueron las ideas de diseño que el equipo había tenido al comienzo del proyecto.

Esto no fue un gran problema al principio, pero el equipo pagado por estas deficiencias dos años más tarde, cuando una refactorización importante fue necesario, ya que la DISEÑO RAZÓN FUNDAMENTAL

no estaba disponible. (Véase también el informe del proyecto en el Capítulo 1,

Proyecto persistor: di fi cultades con las nuevas exigencias, página 58.) Browsing documentos obsoletos, el equipo tuvo dificultades para trabajar a cabo el razonamiento detrás de los cambios de diseño realizados durante los últimos dos años, y se quedó atascado en un callejón sin salida ya explorados por sus colegas.

Creo que la importante conclusión a extraer de esta experiencia es que en cuanto a la actualización de los documentos se refiere, no se puede esperar hasta que realmente se necesita una versión exacta. Este es el momento en el que ya es demasiado tarde. Con bastante frecuencia, las actualizaciones de la documentación no son lo más urgente un proyecto tiene que ver. Pero no hay que confundir urgente con importante. Esperar un poco para actualizaciones de la documentación puede ser justificado - simplemente no espere a que los expertos han dejado el proyecto o están ocupados con otras cosas.

Las experiencias de Proyecto Vista copia de seguridad de este punto de vista (página 186). El hecho de que este proyecto lleva a cabo CONTINUO DOCUMENTACIÓN fue la clave de su éxito. No es que el entorno de las aplicaciones que producía era precisa todo el tiempo - no lo era. Pero a medida que el equipo aprendió más y más sobre las aplicaciones en la organización del cliente y cómo se interrelacionan, se actualiza el entorno de las aplicaciones, que siempre refleja el conocimiento actual y reiteró hacia una descripción exacta.

En lo que se refiere a la planificación de la documentación, hay que tener también en OpenDoors proyecto. La documentación de este proyecto carecía EL PANORAMA, y los documentos que se solapan no hicieron exactamente presente INFORMA- ENFOCADO

Gestión y Aseguramiento de la Calidad

186

Proyecto Vista: actualizaciones regulares al entorno de las aplicaciones

El diagrama con el entorno de las aplicaciones (Figura 7, página 54) se actualiza después de cada entrevista, el equipo de consultoría tuvo con el cliente. De esta manera, el esquema siempre reflejaba el conocimiento actual del equipo tenía 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 conocían, así como las dependencias entre aplicaciones. Al mantener el diagrama hasta la fecha, el equipo podría asegurarse de que cada entrevista trajo una perspectiva adicional.

Debido a que el esquema había sido utilizado con éxito durante el proyecto, el equipo consideró que una técnica similar podría ser utilizado en otros proyectos también. El diagrama de aplicación paisaje se presentó al personal general de la compañía de software en un artículo que apareció en la empresa revista trimestral de la casa. En este artículo se introdujo brevemente el proyecto, y explicó el papel del diagrama había jugado en la especi fi cación del entorno de las aplicaciones. Por otra parte, la especificación (que consistía en esencia, que el diagrama) se convirtió en parte del depósito de documentos de ejemplo para proyectos de consultoría de la compañía de software.

CIÓN. (

Véase también el informe del proyecto en el Capítulo 1, OpenDoors del proyecto: la comunicación, el

diseño la página 55.) Esto se debió principalmente a un problema con la gestión de la documentación en este proyecto: la mayor parte de los documentos no tenían UNO Autor responsable. En lugar de ello, diferentes personas añaden material a la documentación del proyecto de una manera bastante descoordinada. La superposición de documentos e información inconsistente fueron la consecuencia, así como un esfuerzo innecesario pasado en demasiados documentos. Fue no sólo los documentos que se superponen. La documentación refleja las ideas de diseño que se solapan e inconsistentes que estuvieron representados en la arquitectura del portal Web.

Las cosas cambiaron para mejor cuando se produjo un importante refactorización. No sólo fue rediseñado el software, los documentos eran así. Esto podría ocurrir sólo porque en esta etapa de la documentación se consideró Una actividad distinta. Los documentos refactorizado salido bien porque cada uno tenía Un autor RESPONSABLE, que se preocupaba por la calidad de la documentación. hacer circular

En cuanto a los informes de los proyectos persistor, Vista y OpenDoors, nos damos cuenta de que la planificación

documentos

cuidadosa por sí sola no es suficiente para producir la documentación que sea útil y que se utiliza. Los documentos que se utilizaron en gran medida tienen en

187

Informes de experiencia

OpenDoors proyecto: hacer circular la documentación para la retroalimentación

Este proyecto consistió en muchos equipos. El equipo marco extendió un marco que proporciona la funcionalidad básica 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 diseños 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 documentación. La documentación fue un poco mal cuando un número 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 documentación inconsistente en algunos lugares.

En algún momento, los arquitectos decidieron que era hora de un refactorización, por lo que todas las aplicaciones compartirían una arquitectura común. Durante este refactorización, también se abordó la documentación. Un pequeño grupo se hizo cargo de un nuevo conjunto de documentos que por una parte se describe la arquitectura general y los principios de diseño, y por otro cómo se integraron las distintas aplicaciones y cómo se podría implementar en la Web. Estos documentos se sometieron a un proceso de revisión informal. Informales, pero no lo era, le dio la gente de varios departamentos de la oportunidad de compartir sus pensamientos. La documentación 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 codificación real, los equipos que se utilizan para las futuras versiones del marco podría examinar estos conceptos con antelación. Ellos aprendido acerca de lo que podían esperar, sino que también tuvo la oportunidad de formular observaciones sobre los conceptos de diseño. Varios puntos débiles fueron identificado como muchas otras personas ofrecieron sus puntos de vista. Como resultado, se han mejorado tanto la arquitectura general y su documentación. Más que eso, distribución de los documentos y la petición de evaluar contribuyó a la sensación de unidad entre todas las partes implicadas: la compañía de tecnologías, un subcontratista y el cliente. Todo el mundo había estado implicado, aunque de diferentes maneras.

común 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 revisión. Un manifiesto CULTURA REVISIÓN

añade en gran medida a la participación del cliente y permite a los equipos reciben mucha información

sobre lo que han escrito. Proyectos persistor y OpenDoors recibieron una gran cantidad de información útil cuando el docu- marco

Gestión y Aseguramiento de la Calidad

188

mentación se pasó a los usuarios del programa marco. Proyecto Vista aprendido mucho de discutir el entorno de las aplicaciones y lo que aún le faltaba a que muchas de las partes interesadas en la organización del cliente. Ninguna de estas revisiones pasó por un proceso de peso pesado, y el hecho de que la burocracia podría evitarse contribuyó en gran medida a los éxitos de la revisión. Proyecto salir, sin embargo, ofrece una advertencia. mientras que una CRÍTICA 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 situación crítica cuando los documentos fueron distribuidos que no habían sido objeto de una REVISIÓN 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 versión provisional del documento de concepto de reingeniería disponible. Este documento fue importante para el cliente, y dado que la relación con el cliente era bueno, el equipo accedió a entregar el documento preliminar a pesar de que no había sido revisado internamente.

Por desgracia, debido a algunos malentendidos anteriores del dominio de aplicación, el documento contenía algunos errores que no habían 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 entendían. La versión del documento provisional había causado más problemas que beneficios.

El equipo decidió que harían las futuras versiones disponibles sólo después de haber sido revisados ​internamente. Estas revisiones internas nunca llegaron a ser los procedimientos burocráticos, pero se aseguraron que los errores graves en la documentación podría ser fijo antes de que pudieran causar vergüenza innecesaria.

El segundo aspecto de la distribución de los documentos es hacer hincapié en que todo el que escribe un documento es la encargada de ponerse en contacto con el A quién va destinado.

No hay ningún punto en el almacenamiento de un documento en algún 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 INFORMACIÓN mercado. En Proyecto persistor, el equipo invitó a los usuarios del programa marco por correo electrónico a mirar la documentación antes de que se llevaron a cabo talleres. OpenDoors proyecto distribuyen la descripción de la arquitectura de forma activa entre el equipo. Proyecto Vista tomó una copia de su esquema de aplicación horizontal a todas las reuniones.

189

Informes de experiencia

Obtener y

Una buena razón para la producción de un documento es proporcionar una oportunidad para pensar en un

preservar el

tema a través. Esto sucedió en el Proyecto persistor (ver el informe de la experiencia en la página 184). El

conocimiento

equipo había tenido muchos debates pizarra, de la que había surgido una buena idea de la arquitectura general. Pero cuando el equipo comprometido sus ideas de diseño de papel, que se vieron obligados a cavar más profundo. Un proceso de ESCRITURA Y REFLEXIÓN les permitió piensan que sus ideas a través de y para comprobar posibles inconsistencias de datos. Documentación permitió al equipo a definir con precisión el diseño.

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 catalogación. La observación es que las personas más introvertidas tienden a ser más creativos durante la escritura, mientras que las personas más extrovertidas más a menudo que no prefiere trabajar con una pizarra. Dado que algunas personas aprenden mucho durante un proceso de ESCRITURA y la reflexión, es aconsejable mantener esta oportunidad.

Flexicar proyecto: mantener la experiencia dentro de la empresa Los diseñadores han elegido una arquitectura basada en un servidor de aplicaciones y el uso de EJB (Enterprise Java Beans) para poner en práctica la programación óptima de las etapas de producción para la fabricación de automóviles. El documento de diseño 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 documentación en realidad nunca salió de sincronización. Al mismo tiempo, los usuarios del documento hicieron comentarios tanto en la descripción del diseño actual y de lo que se ha descrito.

En el momento en que se completó el proyecto, el documento describe la arquitectura de diseño con mucha precisión, incluyendo una discusión de los pros y los contras del enfoque tecnológico elegido. En este punto, este documento se convirtió útil más allá del proyecto real. El documento pasó a formar parte del repositorio de la compañía para la documentación de diseño, de modo que otros proyectos en diferentes dominios de aplicación podrían 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, ¿cómo tratar con él? El conocimiento debe ser compartido entre el equipo. La documentación es una manera de expresar el conocimiento. La interacción directa, por ejemplo a través de discusiones y talleres, es otra. He mencionado antes que una combinación de ambos es la mejor estrategia para hacer de la sabiduría colectiva de un equipo a disposición de todos los miembros. Cuanto más se ofrece activamente el proyecto de docu-

Gestión y Aseguramiento de la Calidad

190

mentos a la audiencia prevista en una INFORMACIÓN mercado, cuanto más se llega a sus lectores. El papel de la documentación no se limita a los proyectos individuales, sin embargo. Alistair Cockburn menciona que una función importante de la documentación es 'prepararse para el siguiente juego' (Cockburn 2001). Así que hay que identificar los documentos que pueden ser útiles más allá de los límites de su proyecto actual, y hacer los documentos más ampliamente disponible.

Varios informes de proyectos dan ejemplos de cómo se puede hacer esto. Los proyectos Flexicar, AirView y persistor todos contribuyeron a base de conocimientos de la compañía de software - una piscina de información 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 diseño de interfaz gráfica de usuario disponibles Este proyecto fue único en el sentido de que se centra tanto en el diseño de interfaz gráfica de usuario. El diseño involucrado aspectos ergonómicos que no se encuentran normalmente en los proyectos típicos de la compañía de software.

La empresa mantiene un repositorio de éxito especificaciones y diseños 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 reutilización. Los documentos están disponibles a través de una intranet. Colegas pueden buscar esta intranet para documentos que son relevantes para una tecnología en particular oa un dominio de aplicación particular.

Se añadió la documentación del diseño de interfaz gráfica de usuario a este registro, por lo que los futuros proyectos GUI podrían bene fi ciarse de la experiencia adquirida, especialmente con la ergonomía GUI. La documentación también se usó como material ejemplar en un seminario interno en las especi fi caciones, en el que los ingenieros de software más experimentados transmiten sus conocimientos a sus colegas más jóvenes.

Proyecto Vista también contribuyó a que la base de conocimientos, y, además, se convirtió en el tema para un artículo en la revista organización de software en la empresa, como se describe en el informe del proyecto en la página 186. Obviamente, no todos los documentos del proyecto son candidatos para una organización de CONOCIMIENTO ADMINISTRACIÓN.

Sin embargo, cuando un equipo mantiene una ENFOQUE EN EL LARGO PLAZO PERTINENCIA

en lo que se refiere a la documentación, lo más probable es que algunos documentos pueden ser útiles en contextos futuros. Documentos que describen el FUNDAMENTOS DE DISEÑO son particularmente útiles - la discusión de la

191

Informes de experiencia

ventajas y desventajas de diferentes enfoques es exactamente lo que será más útil para proyectos futuros.

Proyecto persistor: alimentar la base de conocimientos de la organización La documentación que se incluye una descripción de la técnica de control de versiones especial la capa de acceso de datos utiliza versiones de dos dimensiones (Figura 21 en la página 89). Esta es una técnica bastante especializado, pero es bastante común para el almacenamiento y recuperación de información en la industria financiera. Una vez que el concepto se había entendido, estaba claro que otros proyectos podrían bene fi cio de la experiencia también.

Un miembro del equipo elaboró ​un documento de introducción para la base de conocimientos de la organización. En este artículo se explica los conceptos básicos de control de versiones de dos dimensiones y se utilizan los mismos ejemplos que tenían el concepto de uso de la estructura. Este documento se podría producir con relativamente poco esfuerzo, ya que la mayoría del material fue fácilmente disponible. Varios colegas utilizaron este documento como fuente de información 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 GESTIÓN DEL CONOCIMIENTO no sólo sobre la recogida de información, sino también de recuperación y uso de la misma. Este proyecto fue capaz de entregar un resultado mucho más rápido debido a que el equipo podría depender de las experiencias de proyectos anteriores - un buen ejemplo de cómo los documentos de interés puede ser en el largo plazo.

Proyecto Contentis: el conocimiento recogido de los requisitos de CMS

Este proyecto tenía un plazo de tiempo más corto en el que el equipo tuvo que subir con una lista de requisitos para un sistema de gestión de contenidos web.

El equipo podría bene fi cio del hecho de que su organización había hecho la consulta sobre los sistemas de gestión de contenidos web antes, y que la experiencia que ya estaba disponible. En pocos días, el equipo tuvo varias listas Ejemplo de requisito de proyectos anteriores en sus manos. Estas listas no podían utilizarse pie de la letra, por supuesto, ya que los requisitos tenían que adaptarse a las necesidades específicas del cliente. De hecho - y como era de esperar - lo que se utiliza la mayor parte del tiempo en el proyecto fue la cifra cuáles eran los requisitos específicos. Sin embargo, las listas de los requisitos de los proyectos anteriores fueron útiles, ya que el equipo no tiene que empezar de cero, pero podría basarse en material existente. Alternativamente, una vez finalizado el proyecto, una nueva lista de requisitos podría añadirse a la base de conocimientos de la organización.

Observaciones finales

Ahora que ha llegado hasta aquí, ¿cuáles son los siguientes pasos? Ha leído los patrones en la documentación á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 documentación y los productos de documentación en su proyecto? En su libro sobre Desarrollo Ágil de Software, Alistair Cockburn recomienda: 'Considerar ágil como una actitud, no una fórmula'. Y continúa: 'En ese estado de ánimo, mira a su proyecto actual y preguntar, ‘¿Cómo podemos, en esta situación, el trabajo de una manera ágil?’' (Cockburn 2001).

Creo que este enfoque es tan viable para la documentación ágil como lo es para el desarrollo ágil de software, y le recomiendo que tome este enfoque cuando se va a solicitar la documentación ágiles en su proyecto. Después de que se ha familiarizado con las ideas generales de la documentación ágil, se puede ver en su proyecto y ver cómo la documentación se puede hacer con un ágil actitud. En este punto, me gustaría recordar los principios de la documentación ágil.

embargo, que proporciona toda la información relevante parasin losningún lectores. documentación del proyecto es más eficaz cuando es ligero, tipo de documentos innecesarios, escriben bien, tratan de hacerlo sin más documentación. Centrarse en los materialesestán adecuados. Lay sin que deben ser pero abordados en documentos escritos. Asegúrese de que estos documentos escritos, se cortas. Un proyecto ágil da preferencia a la documentación de peso ligero. Buscar lossiempre temas en los que siente Más documentación no es siempre mejor que menos. Los documentos largos no son mejores que las

194

Observaciones finales

Los documentos que se consideren necesarios sólo pueden resultar útiles si son de alta calidad: información precisa y actualizada, de fácil 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 propósito bien sólo si es preciso y bien organizado. La rectitud hará sus documentos bien.

Herramientas y técnicas son útiles sólo si facilitan la producción de documentos de alta calidad y hacer que su organización y mantenimiento más fácil.

Adoptar un enfoque imparcial para herramientas. Las herramientas se supone que le ayudará en su trabajo, y la documentación no es una excepción. Si las herramientas hacen que la documentación en su proyecto más difícil, prescindir de ellos. Tenga en cuenta que las técnicas relativamente simples a menudo son su fi ciente para producir documentación útil.

El proceso de documentación 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 documentación. Alistair Cockburn escribe: ' Ágil implica ser eficaz y fácil de manejar. Un ágil proceso es a la vez ligero y su fi ciente'(Cockburn 2001). Acaba de tomar las medidas que sean necesarias: asegúrese de que una buena documentación está escrito, por las personas adecuadas, y con un esfuerzo razonable, pero no hacer planes más allá de ese punto. ¿Cómo puede empezar?

Empieza pequeño. El comenzar pequeño es mucho más prometedora de tratar de lograr todo a la vez, como Mary Lynn Manns y Linda Rising punto de salir cuando recomiendan la introducción 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 fácilmente. Los patrones sobre la estructuración de documentos individuales, por ejemplo, a menudo pueden ser aplicadas inmediatamente. Otras cosas, tales como el establecimiento de procesos, pueden tardar un poco más, pero no requieren un esfuerzo demasiado grande tampoco.

195

Observaciones finales

Integrar estos patrones en su trabajo diario en forma incremental. Si tiene identi fi có un patrón que le gustaría 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 documentación ágil, una actitud de la preparación de documentos de tal manera que sean útiles para los demás, sus clientes y sus colegas por igual. La aplicación de las pautas para la documentación ágil es gratificante en el sentido de que sus lectores apreciarán y pro fi ciarse de su trabajo más. documentación ágil le anima a prescindir de algunos de los trámites que se encuentra en proyectos de más 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 comunicación en su proyecto.

patrón de miniaturas

Encontrar los temas correctos Los lectores de destino ¿Cómo puede el equipo del proyecto asegurarse de que los documentos que producen serán

¿apreciado? En primer lugar, cada documento debe tener un público objetivo, y debe hacer frente a estos lectores con el fin de ser útil. La información centrada

¿Cómo se pueden prevenir los documentos de meandros y llegar a ninguna parte?

A fi cables enfoque claro e identi sobre un tema en particular hace un documento conciso y directo. El documento sencillo ofrece la información relevante a este tema, pero no más que eso.

Individual Requisitos de documentación

¿Cómo se pueden evitar los requisitos de documentación innecesarios?

El enfoque más eficaz para la documentación es para cada proyecto para definir sus requisitos de documentación de forma individual.

Cartera

¿Cómo pueden los equipos de reutilizar el conocimiento sobre la cual podrían ser necesarios documentos en sus

documentación

proyectos?

Una cartera documentación describe los documentos que podrían ser necesarios en un proyecto de software, y su alcance. Si una organización establece dicha cartera, los proyectos pueden elegir aquellos documentos que necesitan, comprobando la necesidad de cada documento individual candidato.

patrón de miniaturas

198

Centrarse en la pertinencia LongTerm

¿Cómo pueden evitar la producción de proyectos de documentación que expira antes de tiempo?

Hay mucho valor en la documentación que se centra en los problemas a largo plazo con una relevancia - cuestiones que desempeñarán un papel en una fase posterior del proyecto o en proyectos futuros.

Especí fi cación como un

¿Cómo pueden los proyectos de desarrollo de asegurar que se dirigen en la dirección que el cliente quiere?

esfuerzo conjunto

Cada proyecto de desarrollo requiere una especificación, que re fl eje el análisis de necesidades realizado conjuntamente por el equipo del proyecto y el cliente. Fundamentos

¿Cómo puede el equipo asegurarse de que se sientan las bases para futuros cambios de diseño?

de diseño

Los documentos de diseño se convierten en una valiosa fuente de información, si no se limitan a describir el diseño actual, pero también se centran en la razón de ser del diseño y explican por qué se eligió el diseño particular. El panorama ¿Cómo se pueden introducir a la gente a un proyecto sin ser confrontado con una

diluvio de información técnica?

Una buena idea de un proyecto es mejor transmite a través de una descripción de la 'gran imagen' de la arquitectura que subyace en el sistema en construcción. La separación de descripción y evaluación

Los ejemplos realistas

¿Cómo pueden los autores evitar la pérdida de credibilidad?

Autores ganan credibilidad si, en sus documentos, que la descripción claramente separada de la evaluación.

¿Cómo puede explicarse abstracto material de una manera comprensible?

Los documentos del proyecto son mucho más convincente si incluyen ejemplos reales de contexto del proyecto.

La estructuración de los documentos individuales La información estructurada

¿Cómo puede la información sea presentada de una manera fácilmente accesible? La mayoría de los documentos del proyecto están mejor organizados como texto secuencial sin embargo, bien estructurado. Esto comienza con los capítulos y secciones bien elegidos, pero también puede extenderse a la utilización de bloques de construcción textual coherente en todo el documento.

La estructuración de los documentos individuales

Diagramas

199

¿Cómo pueden los autores proporcionar una visión general de las estructuras y procesos de una manera conveniente?

juiciosas Los diagramas pueden proporcionar excelentes vistas generales, mientras que un texto que la acompaña explica los detalles en la medida en que sea necesario. Tablas sin ambigüedades

¿Cómo pueden autores presentan información sistemática de una manera precisa?

Mesas ofrecen un formato compacto para la presentación concisa e inequívoca de la información.

Directrices para los

¿Cómo 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 cómo los diferentes grupos de lectores deben acercarse al documento.

Thumbnail Sketches

¿Cómo pueden los lectores obtener una visión general de los temas tratados en un documento?

bocetos en miniatura proporcionan breves descripciones de las secciones de un documento, incluidos los objetivos generales de la sección, así como sus principales ideas.

Referencias trazables

¿Cómo pueden ser documentos vinculados el uno al otro?

Un documento debe incluir referencias a otros documentos sólo si los lectores pueden obtener esos documentos sin mucho esfuerzo.

Glosario

¿Cómo pueden autores asegurarse de que los lectores a comprender el vocabulario utilizado en un documento?

Un glosario puede explicar términos técnicos, así como los términos especí fi cos para el dominio de aplicación.

Historia del documento

¿Cómo se puede evitar la confusión entre las versiones de un 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.

patrón de miniaturas

200

Diseño y la tipografía Texto en el 50% de una página

Dos alfabetos por línea

120% Interlineado

¿Cuánto espacio en una página debe ser dedicado al texto? Alrededor del 50% de la página debe ser dedicado a texto.

¿Cuál es el ancho de la línea óptima?

Aproximadamente dos alfabetos minúsculas del tipo de letra estándar deben encajar en una línea.

¿Cuál es el espaciado de línea óptima? La mejor separación de líneas es aproximadamente 120% del tamaño de letra.

dos Tipos de letra ¿Cuántos tipos de letra son apropiadas y que? En la mayoría de los casos, dos tipos de letra por documento son apropiados - un tipo de letra serif para el texto principal y una tipografía sans serif para los títulos. El uso cuidadoso de las modificaciones de tipo

Sentencia cuidado y sombreado

La colocación adyacente

¿Cómo se pueden destacar partes de un texto?

variaciones de tipo pueden ser utilizados para dar énfasis, pero deben usarse con cuidado. ¿Cómo se pueden separar celdas de la tabla?

Cuidado gobernante y el sombreado conduce a tablas altamente legibles.

¿Cómo pueden las tablas y diagramas pueden integrar en el texto?

Diagramas y tablas están mejor cerca del texto de la que se hace referencia.

Páginas coherentes ¿Qué opciones existen para evitar la paginación incómoda que desgarra informa- relacionados

Tion aparte? La lectura de flujo se apoya en las páginas coherentes - páginas que asegurarse de que aparezca un mínimo de información relacionada a cada lado de un salto de página.

Infraestructura y Organización Técnica

201

Infraestructura y Organización Técnica Paisaje

¿Cómo pueden los miembros del equipo tengan una buena visión general de lo que existe en la documentación de un proyecto?

documento La documentación 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 añadir información. Un paisaje documento que más o menos se forma un árbol se adapte mejor intuición humana.

Archivo de documentos

¿Cómo pueden los proyectos de evitar la pérdida de cualquiera de las versiones de documentos?

documentación de proyecto de archivo ofrece la ventaja de que las versiones se pueden recuperar cuando sea necesario.

wiki

¿Cómo puede la documentación se dará una ventaja más interactivo?

Un Wiki ofrece acceso a la documentación del proyecto a través de un servidor de intranet, y, además, permite al equipo para publicar notas y mensajes a otros según sea necesario.

Código-comentario de

¿Cuál es una manera fácil de mantener la documentación que hace referencia al código real?

proximidad

Documentación del código, en la medida en que un equipo de proyecto considera necesario, es mejor hacerlo a través de comentarios de código fuente. documentos separados deben reservarse para problemas de nivel superior, tales como resúmenes, requisitos, diseño y arquitectura.

De fácil

¿Qué es más apropiado: los documentos destinados a ser utilizados en línea o documentos destinados a la impresión?

lectura-Medios

La elección de un medio debe reflejar el uso típico de un documento. La regla de oro es: impresión es buena para la lectura, en línea es bueno para mirar las cosas. Separación de Contenido y disposición

¿Cómo pueden los diseños de documentos de texto pueden modificar y volver a utilizar fácilmente?

estilos de diseño pueden ser de fi nido y se asigna a porciones de contenido. Estos estilos de diseño se pueden cambiar fácilmente y se pueden reutilizar a través de los documentos.

patrón de miniaturas

202

Fuente única y

¿Cómo pueden los múltiples puntos de vista de un documento pueden crear sin duplicar el mantenimiento?

Objetivos Múltiples

La infraestructura de la documentación puede emplear mecanismos que tienen documentos de origen y generan automáticamente vistas adicionales. Tales mecanismos evitar la doble mantenimiento y garantizar la coherencia.

Importación por referencia

¿Cómo pueden los diferentes documentos utilizar el mismo diagrama o tabla consistente?

Artefactos que deben aparecer en múltiples contextos pueden ser importados por referencia en los documentos que los incluyen.

La separación de procesamiento e impresión

plantillas de

¿Cómo pueden producir proyectos de documentos útiles, imprimibles? Si un equipo elige para entregar la documentación del proyecto en un formato de impresión que está ampliamente disponible, todos los lectores son capaces de imprimir los documentos, independientemente de la plataforma que utilizan.

¿Cómo pueden todos los documentos del proyecto adquirir una estructura razonable y un buen diseño a bajo costo?

documentos

plantillas de documentos, una vez que han sido diseñados adecuadamente, imponen su estructura y el diseño de todos los documentos que se producen de usarlos. pocas herramientas

¿Cómo pueden los proyectos minimizar el esfuerzo dedicado a la introducción y el uso de herramientas de documentación? Casi todos los proyectos pueden manejar con un pequeño conjunto de herramientas de documentación.

Los cambios anotado

¿Cómo pueden los autores evitar la confusión sobre los cambios que han hecho? Mientras que un documento se encuentra en desarrollo, los autores pueden utilizar las anotaciones automáticas para identificar aquellas partes del documento que han cambiado recientemente.

Notificación sobre la actualización

¿Cómo se pueden prevenir los lectores del uso de versiones no actualizadas?

Cada vez que hay un cambio significativo en un documento de proyecto, todos los lectores potenciales deben ser noti fi cado de la nueva versión. La noti fi cación debe explicar más o menos lo que se ha cambiado, pero no debe incluir el material actualizado en sí.

Gestión y Aseguramiento de la Calidad

Reorganización a petición

203

¿Cómo se puede mantener la infraestructura de la documentación?

reorganización frecuente empeora las cosas, no mejor. Reorganización de la infraestructura de la documentación debe tener lugar sólo cuando es solicitado activamente por los miembros del equipo del proyecto.

Gestión y Aseguramiento de la Calidad Una actividad distinta

¿Cómo se deben asignar recursos a las actividades de documentación?

Cuando la documentación se considera una actividad de proyecto distinto, y no sólo el subproducto de codificación, se le puede asignar su propio presupuesto, la prioridad y el horario. Documentación entonces se puede pesar en contra de otras actividades pr oyecto.

Uno responsable Autor

¿Cuántas personas deben ser responsables de un documento?

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.

Documentación continua

Cuando se debe escribir la documentación del proyecto? La documentación 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 reflexión

¿Cómo pueden documentación y otras actividades del proyecto estimular el uno al otro?

Para sacar el máximo partido de la documentación, los miembros del equipo tienen que pasar tiempo en la escritura real, así como en la reflexión sobre lo que han escrito, preferiblemente en un entorno tranquilo.

revisión Cultura ¿Cómo se puede mejorar la calidad de los documentos del proyecto?

La documentación puede bene fi cio muchos de los comentarios, siempre una cultura opinión se ha establecido en la cual ambos autores y los colaboradores se sientan cómodos. Revisión Antes de entrega

¿Cómo pueden los autores recibir la retroalimentación adecuada en el momento adecuado?

Las primeras críticas 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 revisión es obligatoria.

patrón de miniaturas

204

Crítica de consumidor

¿Cómo puede utilizar un equipo de documentación para aumentar la implicación del cliente?

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 añadir a la formación de equipos y la integración.

Una vista distante ¿Cómo pueden los autores obtengan retroalimentación imparcial?

Los autores pueden obtener retroalimentación imparcial de los colaboradores que están interesados ​en el tema y que por lo general tienen conocimiento en el campo, pero que no están involucrados en el trabajo real se describe en el documento.

información del mercado

Gestión del conocimiento

¿Cómo se pueden prevenir buenos documentos de ir tristemente inadvertido? Documentos ganan más atención si los presuntos lectores están invitados activamente para leerlos.

¿Cómo pueden los proyectos futuros bene fi cio de un proyecto exitoso?

Sólo cuando la documentación del proyecto se pone a disposición de toda la organización 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 colección 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 especificación, modelado, diseño, la codificación u otro proceso - que sigue los principios expresados ​en la Manifiesto ágil.

Autor Para los propósitos de este libro, cualquier persona que escribe un proyecto documento. Por lo general se trata de un miembro del equipo que también tiene otras tareas. Casi nunca un escritor técnico profesional.

CASO la ingeniería de software asistida por computadora, como en 'herramienta CASE'.

Glosario

206

Diagrama de clase

UN UML diagrama que muestra las clases, sus atributos y sus operaciones, así como diversas relaciones estáticas que existen entre estas clases, tales como asociación, la agregación y la herencia. Contenido

El texto real de una documento, independiente de diseño o formato. libro de cocina UN documento que se explica cómo utilizar un sistema de software a través del asesoramiento paso a paso.

entregable Cualquier artefacto que un proyecto se supone que debe entregar al cliente. Esto puede incluir el código fuente, software ejecutable y documentos. documento de diseño UN documento que describe cómo el software está organizado internamente y por qué está organizado de esa manera. Por lo general, un documento de diseño describe cómo el software se compone de partes más pequeñas y cómo se relacionan estas partes. Los diagramas de clases y diagramas de interacción son a menudo el método de elección para describir un diseño.

Documento Un artefacto persistente que está configurado específicamente para proporcionar información por escrito. Un documento se produce típicamente por vía electrónica, y se puede leer ya sea como una copia impresa o en línea.

Documentación La totalidad de documentos y comentarios de código fuente producen en un proyecto. También el proceso que comprende la colección, clasificacion y la difusión de información.

Procesamiento de documentos

El proceso de crear, editar, cambiar, mantener e impresión documentos, como se hace típicamente con una procesador de textos. Fuente El conjunto de caracteres que pertenecen a un cierto tipo de letra de un tamaño dado.

207

Glosario

HTML Hipertexto lenguaje de marcas. Un lenguaje utilizado para definir la apariencia y el comportamiento de las páginas cuando se muestra en un navegador Web. HTML permite la definición de bloques de texto, así como la de fi nición de hipervínculos.

hipertexto Texto organizada de una manera no secuencial con hipervínculos proporcionar acceso de un trozo de información a otros. Típicamente, varias rutas de acceso permiten lectores viajar a través de un hipertexto de diferentes maneras. diagrama de interacción

UN UML diagrama que visualiza el paso de mensajes entre los objetos colaboradoras.

Diseño El conjunto de características que definen una documentos apariencia visual.

Legibilidad El grado en que una página impresa se puede reconocer de forma rápida 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 documentación, un trozo de texto o un grupo de palabras clave que proporcionan información sobre el documentos el estado y el tipo de información que contiene.

On-line documento UN documento que está destinado a ser leído con el uso de un navegador web u otra aplicación de visualización. A menudo acceder al documento se da a través de Internet o de una intranet en la casa, pero el documento también pueden estar situados en el equipo local. documentos en línea pueden tener hipervínculos por el cual los documentos pueden ser vinculados.

formato de párrafo Una especificación que define las propiedades de formato para todos los párrafos de un tipo dado dentro de una documento, tal como se utiliza en una procesador de textos.

Glosario

208

PDF Formato de Documento Portátil - un sistema electrónico documento formato desarrollado por Adobe Systems Inc., que es portable entre diferentes tipos de equipos, diseñados para su visualización en línea, pero ahora también se utiliza como una formato de impresión.

Posdata UN documento Descripción lenguaje diseñado para ser una formato de impresión portable entre los dispositivos de impresión.

Imprimir documento UN documento destinado a la impresión, en contraposición a una documento en línea.

formato de impresión

Una especificación que describe exactamente cómo una documento aparecerá cuando se imprima. Ejemplos incluyen PDF y Posdata.

Legibilidad El grado en que un texto puede ser fácilmente agarrado y entendido por el

lector.

Lector Una persona que utiliza una documento para obtener la información en un nivel arbitrario de detalle. Esto incluye no sólo los que leen un documento de principio a fin, sino también a los lectores ocasionales que navegar a través de un documento en búsqueda de información específica.

refactoring Reorganización de un sistema de software sin cambiar su comportamiento externo, con el objetivo de mejorar su estructura interna. Cuando se aplica a la documentación: la mejora de la estructura de la documentación del proyecto sin modificar su contenido.

revisión El proceso de tener una documento revisado por una persona distinta del

autor, típicamente con la intención 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

209

Glosario

software, o puede ser un proyecto de consultoría que todavía tiene que ver con el desarrollo de software, aunque de una manera menos directa.

documento especi fi cación UN documento que describe lo que se supone que un producto de software que hacer. Una especi fi cación 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 diseño y el formato de una clase de documentos similares. Más procesadores de palabras apoyar el uso de plantillas de documentos.

Miniatura Un breve resumen de un texto más largo.

Tutorial UN documento que se explica cómo utilizar un sistema de software.

Tipo de letra

Una colección de caracteres, incluyendo letras, números y símbolos, destinada a la presentación visual de la lengua y todos ellos diseñados en un estilo similar. Los ejemplos incluyen Times, Helvetica, Garamond y Frutiger. La mayoría de los tipos de letra están diseñados como familias e incluyen conjuntos de caracteres para diferentes tamaños, así como las variaciones tales como negrita, cursiva y casquillos pequeños.

tamaño de letra El tamaño de una tipo de letra, normalmente medido en puntos. Un rango típico de tipo tamaños adecuados para impresa documentos es de 8-24 puntos.

Tipografía La ciencia, del arte o el arte de la creación de una página impresa. ofertas de tipografía con letras, diagramas, líneas, superficie y color.

UML Unificado de Modelado del lenguaje.

ARRIBA

Uni Proceso fi ed.

Glosario

210

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 típico. Procesador de textos Para los propósitos 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 autoedición sofisticados.

referencias

Alexander Ishikawa Silverstein 1977 Christopher Alexander, Sara Ishikawa, Murray Silverstein: Un Lenguaje de Patrones -

Poblaciones • Edificios • Construcción, Oxford University Press, Nueva York, 1977. Alexander 1979

Christopher Alexander: La manera atemporal de construcción, Oxford University Press, Nueva York, 1979. Ambler 2002

Scott W. Ambler: Prácticas 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 enseñanza 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 guración patrones de manejo: el trabajo

en equipo, la integración práctica, Addison-Wesley, 2003.

Berleant 2000 Daniel Berleant: '¿Tiene la tipografía afecta la evaluación de propuestas', en

Communications of the ACM, Vol. 43, No. 8, agosto de 2000.

referencias

212

Botafogo Rivlin Shneiderman 1992 Rodrigo A. Botafogo, Ehud Rivlin, Ben Shneiderman: 'Análisis Estructural de hipertextos: Jerarquías identificar y métricas ú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 básica, Nueva York, 1999. Brooks 1995

Frederick P. Brooks: El mes laboral mítico, Addison-Wesley, Anniversary Edition, 1995. Buschmann Meunier Rohnert Sommerlad Stal 1996 Frank Buschmann, Regine Meunier, Hans Rohnert, Peter Sommerlad, Michael Stal: Patrón-Oriented

Software Architecture - un sistema de modelos, John Wiley & Sons, 1996. Cockburn 1998

Alistair Cockburn: Sobrevivir a proyectos orientados a objetos - Guía 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 Gráficas Hoy en día, West Publishing Company, 1985. Coplien 1995 James O. Coplien:

'Un modelo generativo-Proceso de Desarrollo

Lenguaje', en Lenguajes de Patrones de diseño del programa, Vol. 1, James O. Coplien, Douglas C. Schmidt (Eds.), Addison-Wesley, 1995. Coplien 2000

James O. Coplien: "Una lengua del patrón de los escritores Talleres, en

Lenguajes de Patrones de diseño del programa, Vol. 4, Neil Harrison, Brian Foote, Hans Rohnert (Eds.), Addison-Wesley, 2000.

213

referencias

Crowder 1982 Robert G. Crowder: La psicología 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ª edición, Dorset House, 1999.) Dumais 1988 Susan T. Dumais: 'Pruebas de recuperación de información,' en Manual de Interacción

Hombre-Máquina, 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, Universitätsverlag Konstanz. EuroPLoP 1999

Paul Dyson, Martine Devos (Eds.): Actas de la 4ª Conferencia Europea sobre Lenguajes de

Patrones de los programas, 1999, Universitätsverlag Konstanz. EuroPLoP 2000

Martine Devos, Andreas Rüping (Eds.): Actas de la 5ª Conferencia Europea sobre Lenguajes

de Patrones de los programas, 2000, Universitätsverlag Konstanz. EuroPLoP 2001

Andreas Rüping,

Jutta Eckstein, Christa Schwanninger

(Eds.):

Actas de la 6ª Conferencia Europea sobre Lenguajes de Patrones de los programas, 2001, Universitätsverlag Konstanz. Flanagan 2002 David Flanagan: Java en una cáscara de nuez, O'Reilly & Associates, 2002. Fowler 1996

Martin Fowler: Los patrones de análisis, Addison-Wesley, 1996. Fowler 2000

Martin Fowler: UML destilada, 2ª edición, Addison-Wesley, 2000.

referencias

214

Furnas Zacks 1994 George W. Furnas, Jeff Zacks: 'Multitrees: Riqueza y la reutilización de la estructura jerárquica, en' CHI

'94 - Actas de la Conferencia sobre Factores Humanos en Sistemas Informáticos, ACM, 1994. Gabriel 2002

Richard Gabriel: Talleres de escritura, el trabajo de hacer las cosas: Patrones, Poesía ... Addison-Wesley, 2002. Gamma timón Johnson Vlissides 1995 Erich Gamma, Richard Helm, Ralph Johnson, John Vlissides: Patrones de diseño: Elementos

de software reutilizables orientada a objetos, Addison-Wesley, 1995. Glasser 1992

Theodore L. Glasser: 'La objetividad y noticias Sesgo,' en Cuestiones filosóficas en el

periodismo, Elliot D. Cohen (Ed.), Oxford University Press, 1992. Gulbins Kahrmann 1992

Jürgen Gulbins, Christine Kahrmann: Mut zur Typographie, Saltador, 1992. (en alemán) Haramundanis 1998

Katherine Haramundanis, El arte de la documentación técnica, Butterworth-Heinemann, 1998. Harrison 1996 "Los patrones de organización de equipos, en Patrón Idiomas del diseño del programa, Vol. 2, John M. Vlissides, James O. Coplien, Norman L.

Neil B. Harrison:

Kerth (Eds.), Addison-Wesley, 1996. Harrison 2000 Neil B. Harrison: 'La lengua del patrón de pastoreo', en Lenguajes de Patrones de diseño

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.

215

referencias

cuerno de 1989

Robert E. Horn: Mapeo de hipertexto, Lexington Institute, 1989. Horton 1994

William Horton: El diseño y la documentación en línea de escritura, John Wiley & Sons, 2ª edición, 1994. Hsu Mitchell 1997 Richard C. Hsu, William E. Mitchell: 'Después de 400 años, de impresión 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: Programación leer y escribir, Centro para el Estudio de la Lengua y de la Información, 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 introducción de nuevas

ideas en las Organizaciones, 2003 (en preparación). Miller 1956

George A. Miller: 'El número mágico siete, más o menos dos: algunos límites en nuestra capacidad de procesamiento de información', en Psychological Review, Vol. 63, N ° 2, American Psychological Association, marzo de 1956. Nielsen 2000 Jakob Nielsen: El diseño de Usabilidad Web - La práctica de la simplicidad, New Riders Publishing, 2000.

referencias

216

Noble Weir 2000 James Noble, Charles Weir: Software pequeña de memoria, Addison-Wesley,

2000.

Orenstein 1996 Robert Orenstein: 'Una lengua del patrón para un sitio Web de Ensayo-base', en

Lenguajes de Patrones de diseño del programa, Vol. 2, John M. Vlissides, James

O. Coplien, Norman L. Kerth (Eds.), Addison-Wesley, 1996. Pinker 1997 Steven Pinker: ¿Cómo funciona la mente, Allen Lane, The Penguin Press, 1997.

PLoPD 1995 James O. Coplien, Douglas C. Schmidt (Eds.): Lenguajes de Patrones de diseño del programa, Vol. 1, Addison-Wesley, 1995. PLoPD 1996 John M. Vlissides, James O. Coplien, Norman L. Kerth (Eds.): Lenguajes de Patrones de diseño

del programa, Vol. 2, Addison-Wesley, 1996. PLoPD 1998 Robert C. Martin, Dirk Riehle, Frank Buschmann (Eds.): Lenguajes de Patrones de diseño

del programa, Vol. 3, Addison-Wesley, 1998. PLoPD 2000 Neil Harrison, Brian Foote, Hans Rohnert (Eds.): Lenguajes de Patrones de diseño del programa, Vol. 4, Addison-Wesley, 2000. Parnas 1972

David Parnas: 'En los criterios que se utilizarán en Sistemas descomponiéndose en los módulos', 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 preparación). prensa 2000

Larry Press: 'A partir de P-libros a los libros electrónicos', en Communications of the ACM,

Vol. 43, nº 5, mayo de 2000.

217

referencias

2000a Rising Linda Rising: 'los patrones de interacción del cliente', en Lenguajes de Patrones de Diseño 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. Rüping 1998a Andreas Rüping: 'La estructura y disposición de los Documentos Técnicos', en

Actas de la 3ª Conferencia Europea sobre Lenguajes de Patrones de Programación y Computación 1998, Jens Coldewey, Paul Dyson (Eds.), Universitätsverlag Konstanz. Rüping 1998b Andreas Rüping: 'La escritura y la revisión de los Documentos Técnicos', en

Actas de la 3ª Conferencia Europea sobre Lenguajes de Patrones de Programación y Computación 1998, Jens Coldewey, Paul Dyson (Eds.), Universitätsverlag Konstanz. 1999a Ruping Andreas Rüping: 'Gestión de Documentación del proyecto', en Actas de la 4ª Conferencia

Europea sobre Lenguajes de Patrones de Programación y Computación 1999, Paul Dyson, Martine Devos (Eds.), Universitätsverlag Konstanz. Rüping 1999b

Andreas Rüping: 'La tipografía y la autoedición', en Actas de la 4ª Conferencia Europea

sobre Lenguajes de Patrones de Programación y Computación 1999, Paul Dyson, Martine Devos (Eds.), Universitätsverlag Konstanz. Salton 1989

Gerard Salton: Procesamiento automático de texto - La transformación, análisis y recuperación de información por ordenador, Addison-Wesley, 1989.

referencias

218

Schmidt Stal Rohnert Buschmann 2000

Douglas Schmidt, Michael Stal, Hans Rohnert, Frank Buschmann:

Patrón-Oriented Software Architecture 2 - Patrones para concurrentes y en red, objetos, John Wiley & Sons, 2000. Schneider 1996 Wolf Schneider: Deutsch für Kenner - Die neue Stilkunde, Piper, 1996. (en alemán) Schneider 1999 Wolf Schneider: Deutsch für Pro fi s - Wege zu gutem Stil, Goldmann, 1999. (en alemán) 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 alemán) Sommerville 1996 Ian Sommerville: Ingeniería de software, Addison-Wesley, 1996. Strunk Blanca 1979

William Strunk, EB White: Los elementos del estilo, Macmillan, 3ª edición, 1979. Tinker 1963 Miles A. Tinker: Legibilidad de impresión, Iowa State University Press, 1963. Tufte 1997

Edward R. Tufte: Explicaciones visuales: Imágenes y cantidades, las pruebas y la narrativa, Gráficos Press, 1997. Tufte 2001

Edward R. Tufte: El Visual Display de información cuantitativa, Gráficos Press, 2ª edición, 2001. Völter Schmid Wolff 2002 Markus Völter, Alexander Schmid, Eberhard Wolff: Matrices de componentes del servidor -

Componente Infraestructuras ilustrado con EJB, John Wiley & Sons, 2002.

219

referencias

Weinberg 1998 Gerald M. Weinberg: La psicología de la programación informática, Aniversario de plata Edición, Dorset House, 1998. Weir 1997 Charles Weir: 'Patrones de diseño en Equipos: Equipos Cómo puede mejorar el proceso de diseño', en Lenguajes de Patrones de diseño 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 diseño y la

tipografía, Watson Guptill, 1990.

Índice

120% LÍNEA 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

UN DISTINTO ACTIVIDAD 29,

cómo leer xv organización xiii-xiv

161 - 164, 168, 170, 183, diagrama 186 Actividad 72

alcance xii

Desarrollo de software adaptativo 2 Ad-hoc Correcciones 167 ADYACENTE COLOCACIÓN 109

do

- 111 Agile

La cámara, la captura de la información 143

Alliance 1, 205

FALLO DE CUIDADO y sombreado 70,

actitud ágil 193

El uso cuidadoso de variaciones de tipo 44,

Desarrollo ágil xiii, 1, 2, 3, 22, 35, 38, 144, 162, 163, 176, 205

74, 108 - 109 70, 78, 106, 106 -

107, la herramienta 109 CASE 143, 150, 153

y documentación 3 Manifiesto ágil ix, xiii, 1, 2, 22, 38, 144, 167, 173, 176, 182, 205

Cell, separando 108 Diagrama de clase 68, 71, 72, 83, 155, 206 Código, documentación 126

Modelado ágil 2, 3, 28, 30, 38

PROXIMIDAD CÓDIGO-COMENTARIO 126

proceso ágil 194, 205

PÁGINAS COHERENTE 111,

Los ecosistemas ágiles de desarrollo de software 2, 3

guración Con 112 143

Análisis, con el cliente 37

Contenido 56, 62, 63, 88, 114, 131, 132, 135, 206

ANOTADO CAMBIOS 144

Gestión de contenido 17, 57, 88, 114, 131, 191

- 145 Descripción de

- 127, 153

111 - gestión fi

la arquitectura 72

formato independiente del contenido 132

Arquitectura, diseño de comunicación 41

DOCUMENTACIÓN CONTINUA 82,

ARCHIVO, beneficios 124

Autor 7, 42, 43, 64, 97, 104, 120, 125, 140, 141, 144, 145, 146, 161, 164, 165, 168, 169, 170, 171, 172,

146, 165, 166 - 168,

170, 175, 182, 185 Cookbook 32, 206

Creador-Crítico 178 cristal 3

173, 175, 178, 184, 205 conocer la opinión 174, 177

requisitos de captura del cliente 36

mantener la credibilidad 42, 57

múltiple 144, 164

el aumento de la participación 175 CRÍTICA DE CONSUMIDOR 38,

170, 175 - 177, 178, 188

Índice

222

entregable 206

portafolio 30

diagrama de despliegue 72

la preparación para la impresión 138

Descripción, la separación de evaluación 43

visión general que presenta 77

Diseño

impresión 98, 107, 115, 128, 131, 138, 208

comunicado 41

vs impresión en línea 128

razón fundamental 39

tratamiento 138, 206

documento de diseño 20, 31, 34, 39, 45, 48, 51, 53, 55, 58,

productor 153

68, 79, 82, 83, 129, 136, 140, 153, 155, 166, 184,

revisión 25, 165, 170-174, 174-175, 178, 187, 208

185, 189, 206

diagramas de intercambio 136

DISEÑO RAZÓN FUNDAMENTAL 34,

36, 39 - 40, 46, 57, 182, 185, 190 de diseño, lo que

especí fi cación 31, 34, 36, 40, 45, 47, 48, 49, 51, 140, 209

permite el cambio 39

Diagrama 70-72, 88 integrando en el texto 109

almacenamiento y recuperación 149

estructura xiv, 64, 66-70, 74, 82, 165, 169

compartir documentos 136

modelo 97, 141, 147, 151, 209

utilizar en visión general 71

seguimiento de los cambios 144

uso de 70

cámara digital, captura de información 143 Diversidad de los miembros 178 Documento la asignación de la responsabilidad 164

y ejemplos 45 y varios autores 144 circulación 186

elementos útiles 85 DOCUMENTO DE ARCHIVO 82,

123 - 125, 126, 135, 137, 146,

148, 149 HISTORIA DEL DOCUMENTO 70,

documento horizontal 27,

76, 81 - 82, 85, 141, 146, 167

72, 120 - 123, 124, 126, 146,

148, 149, 152, 156, 182 plantillas de documentos 94,

130, 132, 133, 139 - 142, 148, 156

Documentación 206

estructura de control 139 el control de versiones 145

alertar a los lectores 75

coordinar las aportaciones 165

distribuyendo recursos 161

la creación de vista múltiple 133

y proyectos futuros 180

definición 206

y otras actividades 168

diseño 39, 98, 100, 102, 104, 106, 107, 108, 109,

y programación 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 terminología 79

requisitos de fi nir 29

enfoque 26

código de documentación 126

historia 81

asegurando un valor duradero 34

la identificación de lectores 24

entorno para la creación de 169

la identificación de las versiones 81

explicando la información abstracta 44

invitando a los lectores 179

hacerse notar 179

enlace 78

ayudar a los nuevos empleados 40

haciendo flexibles 131

cómo hacer útil 24

administración 31

mejora de la calidad 170

en línea xiv, 98, 107, 128, 129, 130, 131, 143, 153, 207

en forma de árbol 121

involucrando al cliente 175

223

Índice

relevancia a largo plazo 35

Retroalimentación, cómo obtener 177

mantener la atención 26

ALGUNOS INSTRUMENTOS 139,

mantenimiento de la infraestructura 147

Centrarse en la pertinencia LARGO PLAZO 33,

hacer accesible 66

142 - 144, 156

34 - 36, 40, 57,

168, 182, 190

haciendo interactivo 125

La información centrada 25,

minimizando el esfuerzo 142

137, 175, 185 fuentes

visión general que presenta 120

26 - 27, 34, 44, 70, 79, 123,

206

la preservación de las versiones 123

elección para el énfasis 106, 107

procesos y planes 182

elegir 104

cartera de proyectos 31

tamaño 100

papel de 2

estilo 107

uso de serif 105

la especificación de requisitos 28

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 comunicación cara a cara 20 GRAMO

cuándo escribir 166 DOCUMENTACIÓN PORTAFOLIO 27,

29, 30 - 34, 36, 45, 47, 163

GLOSARIO 25,

70, 79 - 81, 86, 141 Glosario, el valor en

la documentación 80

Dominio, explicando la terminología 80

DIRECTRICES PARA LOS LECTORES 25,

70, 72, 75 - 76, 78, 80, 82,

86, 123, 141 Directrices, su uso en la documentación 76

mi

El énfasis, en el texto 106, 107

atraer a los clientes 38

MARIDO

Ejemplo proyecto AirView 16,

La partida, la elección de un tipo de letra 105

47, 190

HTML 132, 133, 134, 135, 150, 207

editor 143

Contentis 17, 57, 191

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

Paracelso 12, 46, 156

REQUISITOS DE DOCUMENTACIÓN INDIVIDUALES 28

persistor 14, 47, 50, 58, 88, 153, 184, 191 Vista 14, 53, 154, 186

- 137, 148, 149

- 30, 33,

49, 144, 163 Material de información abstracta 44

Webber 12, 56

Ejemplos, valor de 45 informes de la experiencia 46-59, 82-91, 112-114, 149-157,

182-191 Expertos al alcance del oído 21 La programación extrema 2, 28

abstrayendo 75

hacer accesible 66 visión general que presenta 77

la presentación sistemática 73 Marketplace Información 36,

126, 179 - 180, 188, diagrama 190

Interacción 32, 72, 206, 207

Imagen introductoria 131

F

Comunicación cara a cara xi, 3, 19, 20, 22, 34, 36, 37, 50, 55, 57, 64

Sección introductoria 131

Índice

224

JUICIOSO ESQUEMAS 42,

70, 70 - 72, 82, 88, 144

K

Página evitando roturas 111 optimización 111

Conocer al cliente captura de 176

espacio para el texto 98, 99

Conocimiento 35

formato de párrafo 141, 144, 207 lenguaje de patrones 5, 6

extracción y transferencia de 181

Patrones y experiencia de dominio 6

administración 31, 181, 182 conservación xi, 57, 189

más recursos 7

reutilización 30

en la arquitectura 6

transferir 3, 24, 48, 181

estructura 8

CONOCIMIENTO ADMINISTRACIÓN 36,

180, 180 - 182, 190

¿Qué son? 5 PDF 139, 144, 150, 153, 208

L

lector PDF 143

Diseño 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 impresión 138, 139, 208

Legibilidad xiv, 93, 94, 97, 98, 102, 105, 106, 107, 108,

115, 207

Proceso, presentando visión general 70

Programación y documentación 148

Línea

Proyecto de diseño de la comunicación 41

separación ó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 documentación de fi nir 29 Resumen de la documentación 120

METRO

alcance la documentación 30

documento de gestión 31

documentar estados estables 167

analista mercenaria 178

hacer que la gente a la velocidad 40

Meta-información 207

la protección de la documentación 123

especí fi cación 37

norte NOTIFICACIÓN SOBRE ACTUALIZAR 145

- 146, 149, 179

Proyecto AirView, la experiencia 47, 190 Proyecto Contentis, la experiencia 57, 191

Proyecto liberarse, la experiencia 47, 90, 188

O UNO RESPONSABLE AUTOR 126,

145, 164, 164 - 165, 168,

175, 185, 186 documentos on-line xiv, 98, 107, 128, 129, 130, 131,

143, 153, 207 Propietario por entregable 165

Proyecto Flexicar, la experiencia 58, 153, 189 Proyecto Flexicar, la experiencia 48 Navegador de proyectos, la experiencia 51, 155

OpenDoors proyecto 64 OpenDoors de proyectos, experiencia 55, 187

Proyecto Paracelso, la experiencia 46, 156 La experiencia del proyecto persistor 47, 50, 58, 88, 153, 184, 191

el panorama 52

225

Índice

proyecto Vista

El sombreado, el uso de 108 FUENTE ÚNICA Y OBJETIVOS DE MÚLTIPLES 130,

entorno de las aplicaciones 54

experiencia 53, 154, 186

132, 133 -

135, 148, 149, 154 proyectos

Proyecto Webber, la experiencia 56

de software 208 ESPECIFICACIONES como un esfuerzo conjunto 34,

Q

36, 36 - 39, 45, 51, documento de

cationes 80 Speci fi 31, 34, 36, 40, 45, 47, 48, 49,

La calidad, de los documentos 170

51, 140, 209 R

Hoja de cálculo 90, 143, 154

Legibilidad xiv, 69, 208

Diagrama de estado 72

optimización 111

Paso a paso 194 Estructura, descripción que

Lector 208

presenta 70

y versiones correctas 145

La información estructurada 27,

la identificación de objetivos 24

44, 66 - 70, 72, 74, 78, 82,

107, 109, 112

instrucciones a 76 MEDIA de fácil lectura 79,

98, 122, 127, 128 - 131, 152,

153, 168

T Mesa 88

REALISTA EJEMPLOS 25,

39, 40, 41, 44 - 46, 58, 175 Refactoring 13,

20, 21, 49, 185, 187, 208

diseño 108 integrando en el texto 109

compartir documentos 136

Referencia, el uso en la documentación 78 REORGANIZACIÓN EN SOLICITUD 135,

137, 142, 147 -

149, 154

utilizar para presentar los datos 74 lectores de destino 24

De recursos, la asignación de la documentación 161

- 25, 27, 29, 33, 36, 46, 49, 76, 79,

122, 175, 178, 180, 188 Plantilla 97,

revisión 25, 42, 47, 48, 57, 165, 187, 208

141, 147, 151, 209

cultura 7

y la estructura 140

proceso 7

Terminología, explicando 79

tipos 178

texto enfatizando 106, 107

el material sin revisar 188 REVISIÓN ANTES DE ENTREGA 164,

165, 170, 174 - 175, 185, 188

espacio en la página 98, 99 el uso de bloques de construcción 68

REVISIÓN CULTURA 42,

164, 168, 170, 170 - 174, 177, 178,

182, 187

uso de estilos 132 TEXTO EN

Crítico, la elección 177

50% De una página 98 - 100, 102, 112

EL PANORAMA 25,

34, 36, 40 - 42, 52, 53, 72, 88, 182, 185 Miniatura 209

Gobernante, el uso de 108

S

patrón 197-204

Alcance del libro xii

utilizar en la documentación 77

Melé 2 SEPARACIÓN DE Contenido y disposición 131

Thumbnail Sketches 70,

141, 144, 148 SEPARACIÓN DE DESCRIPCIÓN Y EVALUACIÓN 42

- 44,

57, 74 SEPARACIÓN DE Procesamiento e impresión 138

144, 148

76, 77 - 78, 79, 85, 107 de la herramienta, la elección 142

- 133, 135,

- 139,

Referencias trazable 70,

78 - 79, 86 Tutorial 32,

209 Dos alfabetos POR LÍNEA 100,

dos tipos de letra 100,

100 - 102, 104

104 - 106

Índice

226

tamaño de letra 101, 102, 103, 104, 105, 209

Tipo de letra 101, 102, 103, 105, 106, 108, 139, 206, 207, 209

documentos de seguimiento 145

Ver, del documento 133

y la longitud de la línea de 101

W

elegir 104

navegador web 143, 207

Tipografía 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,

AMBIGÜEDADES MESAS 44,

104, 110, 112, 130,

70, 73 - 74, 85, 89, 109 Uni fi Proceso ed 33,

125 - 126, 150, 180, 182 Procesador de textos xiv, 94, 97, 103,

132, 133, 134, 137, 138, 140, 143, 144, 145, 209, 210

209 ARRIBA 33, 209

caso de uso 17, 32, 33, 38, 39, 40, 45, 47, 57, 71, 210

ESCRITURA Y REFLEXIÓN 164,

ambiente 169

V Versión

identificar 81

x XP 2, 28

168, 168 - 170, 182, 189 escritura, el medio