Machine Translated by Google

Norma IEEE 1063-2001

(Revisión de IEEE Std 1063-1987)

1063TM
Estándar IEEE para usuarios de software
Documentación

Sociedad informática IEEE

Patrocinado por el
Comité de Normas de Ingeniería de Software

Publicado por el
Instituto de Ingenieros Eléctricos y Electrónicos, Inc.
3 Park Avenue, Nueva York, NY 10016-5997, EE. UU.
Imprimir: SH94976
20 de diciembre de 2001 PDF: SS94976
Machine Translated by Google

Norma IEEE 1063-2001

(Revisión de
Estándar IEEE 1063-1987)

Estándar IEEE para usuarios de software

Documentación

Patrocinador

Comité de Normas de Ingeniería de Software de la

Sociedad informática IEEE

Aprobado el 5 de diciembre de 2001

Junta de estándares IEEE-SA

Resumen: En esta norma se proporcionan los requisitos mínimos para la estructura, el contenido de la información y el formato de la documentación
del usuario, incluidos los documentos impresos y electrónicos utilizados en el entorno de trabajo por los usuarios de sistemas que contienen software.

Palabras clave: ayuda en línea, documentación del usuario del software, manual del usuario

El Instituto de Ingenieros Eléctricos y Electrónicos, Inc.

3 Park Avenue, Nueva York, NY 10016-5997, EE. UU.

Copyright © 2001 por el Instituto de Ingenieros Eléctricos y Electrónicos, Inc.

Todos los derechos reservados. Publicado el 20 de diciembre de 2001. Impreso en los Estados Unidos de América.

Imprimir: ISBN 0-7381-3098-2 SH94976

PDF: ISBN 0-7381-3099-0 SS94976

Ninguna parte de esta publicación puede reproducirse de ninguna forma, en un sistema de recuperación electrónico o de otra manera, sin el permiso previo
por escrito del editor.
Machine Translated by Google

Los documentos de estándares IEEE se desarrollan dentro de las Sociedades IEEE y los Comités coordinadores de estándares de la Junta de estándares de la Asociación
de estándares IEEE (IEEE-SA). El IEEE desarrolla sus estándares a través de un proceso de desarrollo por consenso, aprobado por el Instituto Nacional Estadounidense de
Estándares, que reúne a voluntarios que representan diversos puntos de vista e intereses para lograr el producto final. Los voluntarios no son necesariamente miembros del
Instituto y sirven sin compensación. Si bien el IEEE administra el proceso y establece reglas para promover la equidad en el proceso de desarrollo de consenso, el IEEE no
evalúa, prueba ni verifica de forma independiente la exactitud de la información contenida en sus estándares.

El uso de un estándar IEEE es totalmente voluntario. El IEEE se exime de responsabilidad por cualquier lesión personal, propiedad u otro daño, de cualquier naturaleza, ya
sea especial, indirecto, consecuente o compensatorio, que resulte directa o indirectamente de la publicación, el uso o la confianza en este o cualquier otro IEEE. Documento
estándar.

El IEEE no garantiza ni representa la precisión o el contenido del material contenido en este documento, y rechaza expresamente cualquier garantía expresa o implícita,
incluida cualquier garantía implícita de comerciabilidad o idoneidad para un propósito específico, o que el uso del material contenido en este documento es gratuito. de la
infracción de patente. Los documentos de las normas IEEE se suministran "TAL CUAL".

La existencia de un estándar IEEE no implica que no haya otras formas de producir, probar, medir, comprar, comercializar o proporcionar otros bienes y servicios relacionados
con el alcance del estándar IEEE. Además, el punto de vista expresado en el momento en que se aprueba y emite un estándar está sujeto a cambios provocados por
desarrollos en el estado del arte y comentarios recibidos de los usuarios del estándar. Cada estándar IEEE está sujeto a revisión al menos cada cinco años para revisión o
reafirmación. Cuando un documento tiene más de cinco años y no ha sido reafirmado, es razonable concluir que su contenido, aunque todavía tiene algún valor, no refleja
completamente el estado actual de la técnica. Se advierte a los usuarios que verifiquen para determinar si tienen la última edición de cualquier estándar IEEE.

Al publicar y poner a disposición este documento, el IEEE no está sugiriendo ni prestando servicios profesionales o de otro tipo para, o en nombre de, ninguna persona o
entidad. El IEEE tampoco se compromete a realizar ningún deber que cualquier otra persona o entidad le deba a otra. Cualquier persona que utilice este y cualquier otro
documento de Normas IEEE, debe confiar en el consejo de un profesional competente para determinar el ejercicio del cuidado razonable en cualquier circunstancia dada.

Interpretaciones: Ocasionalmente, pueden surgir preguntas sobre el significado de partes de los estándares en relación con aplicaciones específicas. Cuando se llame la
atención del IEEE sobre la necesidad de interpretaciones, el Instituto iniciará acciones para preparar las respuestas apropiadas. Dado que los estándares IEEE representan
un consenso de intereses interesados, es importante asegurarse de que cualquier interpretación también haya recibido la concurrencia de un equilibrio de intereses. Por
esta razón, el IEEE y los miembros de sus sociedades y los Comités Coordinadores de Estándares no pueden brindar una respuesta instantánea a las solicitudes de
interpretación, excepto en aquellos casos en los que el asunto haya recibido una consideración formal previamente.

Los comentarios para la revisión de los estándares IEEE son bienvenidos por parte de cualquier parte interesada, independientemente de la afiliación de membresía con
IEEE. Las sugerencias de cambios en los documentos deben tener la forma de una propuesta de cambio de texto, junto con los comentarios de apoyo apropiados. Los
comentarios sobre las normas y las solicitudes de interpretaciones deben dirigirse a:

Secretario, Junta de Normas IEEE-SA

445 azadas carril
apartado de correos 1331

Piscataway, Nueva Jersey 08855-1331

EE.UU

Nota: Se llama la atención sobre la posibilidad de que la implementación de este estándar requiera el uso de materia cubierta por derechos de patente.
Mediante la publicación de esta norma, no se toma ninguna posición con respecto a la existencia o validez de cualquier derecho de patente en relación con
la misma. El IEEE no será responsable de identificar las patentes para las cuales se puede requerir una licencia por un estándar IEEE o de realizar
investigaciones sobre la validez legal o el alcance de aquellas patentes que se le presenten.

El IEEE y sus designados son las únicas entidades que pueden autorizar el uso de las marcas de certificación y/o marcas comerciales propiedad del IEEE para indicar el
cumplimiento de los materiales establecidos en este documento.

La autorización para fotocopiar partes de cualquier estándar individual para uso interno o personal es otorgada por el Instituto de Ingenieros Eléctricos y Electrónicos, Inc.,
siempre que se pague la tarifa correspondiente al Centro de autorización de derechos de autor. Para organizar el pago de la tarifa de licencia, comuníquese con Copyright
Clearance Center, Customer Service, 222 Rosewood Drive, Danvers, MA 01923 EE. UU.; +1 978 750 8400. También se puede obtener permiso para fotocopiar partes de
cualquier estándar individual para uso educativo en el aula a través del Centro de autorización de derechos de autor.
Machine Translated by Google

Introducción
(Esta introducción no forma parte de IEEE Std 1063-2001, IEEE Standard for Software User Documentation).

Dos factores motivaron el desarrollo original de este estándar en 1987: la preocupación de las comunidades de usuarios de
software por la mala calidad de gran parte de la documentación del usuario y la necesidad de requisitos expresados por los
productores de documentación. Desde su adopción, IEEE Std 1063-1987 ha tenido un amplio uso en la preparación de
manuales de usuario impresos y ha contribuido a mejorar la calidad de la documentación.

Debido a la prevalencia de la ayuda en línea y la documentación del usuario en formato electrónico, el estándar se revisó por
completo para abordar la documentación del usuario impresa y electrónica.

La documentación del usuario que cumpla con este estándar también cumplirá con los requisitos de una descripción de la
documentación del usuario según lo prescrito por IEEE/EIA 12207.1-1997. En particular, se cumplirían los requisitos de las
subcláusulas 5.1 y 6.30 de esa norma.

Al comienzo de la planificación de la documentación, se debe identificar el software, sus interfaces de usuario y las tareas que
los usuarios realizan con el software. La documentación de usuario exitosa es el resultado de una identificación adecuada de
la audiencia, un software cuidadoso y un diseño de documentos, y un buen estilo de escritura, además de los requisitos de
estructura, contenido y formato abordados por este estándar. La prueba definitiva de la documentación del usuario del software
es que sea fácilmente utilizable por su público objetivo para el propósito previsto.

En el momento en que se completó esta norma, el grupo de trabajo tenía los siguientes miembros:

Annette D. Reilly, Presidenta

Philip Bernick, Secretario

Selim Aisi Jeanette Evans Mark L. Levinson

bill albing Carl-Heinz Gabriel Dana B. Mackonis
ahumado desnudo Michael Graham Joan Michaeli Alma
Carsten Behren Johannes Graubner Nahigian Elizabeth L.
juan campana Gertrud Grünwied Karl Reed Elmar Roberg
Janean Bowen A. Hakkarainen Clyde Ann Rockley Roberta
Janice Carlson Hatter George F. Hayhoe A. Rupel Lina Scorza
giovanna chiozzi Ralph Hornbeck Joel Subrato Sensharma
phil cohen Howard Holly Jahangiri Elna R. Tymes Dave
Scott De Loach Jacques LeCavalier Versdahl Dave Whelan
yvette duncan Robert Lessman
verna dunn
miriam eldridge

Copyright © 2001 IEEE. Todos los derechos reservados. iii

Machine Translated by Google

Las siguientes personas estaban en el comité de votación:

Theodore K. Atchinson Eva Freund James W. Moore

Edward E. Bartlett Andrew Gabb Francisco Navas Plano
Barbara K. Beauchamp Barry L. Garner Alexander J. Polack
Richard E. Biehl Juris Gregg Giesler Annette D. Reilly R.
Borzovs Kathleen L. Julio Gonzalez-Sanz Waldo Roth Terence P.
Briggs Joseph Butchko Lewis Gray LM Rout
Edward R. Byrne Keith Gunther George F. Helmut Sandmayr
Chan Keith Chow Antonio Hayhoe Rick Hefner Frederico Sousa Santos
M. Cicu Sylvain Clermont James H. Heil Mark Robert J. Schaaf Norman
Francois Coallier Heinrich Mark O. Schneidewind David J.
Rosemary Coleman Paul Henley Debra Schultz Subrato
R. Croll Gregory T. Daich Herrmann John W. Sensharma Robert W.
Taz Daughtrey Bostjan Horch Peter L. Hung Shillato Robert Spillers
K. Derganc Perry R. George Jackelen Neil Fred J. Strauss Toru
DeWeese Franz D. G. Jacobson Thomas Takeshita Mark-Rene
Engelmann William M. Kurihara J. Dennis Uchida Glenn D.
Eventoff John W. Lawrence Jim J. Venables Scott A.
Fendrich Julian Forster Logan John Lord Stan Whitmire
John H. Fowler Magee Tomoo
Matsubara Ian R. Paul AT Wolfgang
McChesney Denis C. Paul R. Trabajo Don
Meredith Wright Natalie C.
Yopconka Geraldine
Zimmerman

Cuando el Consejo de Normas de IEEE-SA aprobó esta norma el 5 de diciembre de 2001, tenía los siguientes miembros:

Donald N. Heirman, Presidente

James T. Carlo, Vicepresidente
Judith Gorman, Secretaria

Satish K. Aggarwal James H. Gurney James W. Moore

Mark D. Bowman Richard J. Holleman Robert F. Munzner
Gary R. Engmann Lowell G. Johnson Ronald C. Petersen
Harold E. Epstein H. Robert J. Kennelly Gerald H. Peterson
Landis Floyd Jay Joseph L. Koepfinger* John B. Posey Gary
Forster* Howard M. Peter H. Lips L. Bruce S. Robinson Akio
Frazier Rubén D. McClung Daleep C. Tojo Donald W.
Garzón Mohla Zipse

*Miembro Emérito

También se incluye el siguiente enlace de la Junta de Normas de IEEE-SA sin derecho a voto:

Alan Cookson, representante de NIST

Donald R. Volzka, representante de TAB

Catherine KN Berger
Andrew D. Ickowicz
Editores de proyectos de estándares IEEE

IV Copyright © 2001 IEEE. Todos los derechos reservados.

Machine Translated by Google

Contenido

1. Visión de conjunto................................................. .................................................... .......................................... 1

1.1 Alcance ................................................ .................................................... .......................................... 1

1.2 Propósito.................................................. .................................................... ............................................. 1
1.3 Organización de la norma ............................................... .................................................... ......... 1
1.4 Usos candidatos ............................................... .................................................... ............................ 2

2. Definiciones.................................................. .................................................... ....................................... 2

3. Estructura de la documentación del usuario del software .................................. .......................................... 3

3.1 Estructura general de la documentación ............................................... .......................................... 4

3.2 Componentes iniciales.................................................... .................................................... ....................... 5

3.3 Ubicación de la información crítica.................................................... .................................................... .. 5

4. Contenido de la información de la documentación del usuario del software .................................. .......................... 5

4.1 Completitud de la información ............................................... .................................................... ....... 6

4.2 Precisión de la información ............................................... .................................................... ............. 6
4.3 Contenido de los datos de identificación ............................................... .................................................... ........ 6
4.4 Información para el uso de la documentación ........................................... .......................................... 7

4.5 Concepto de operaciones .............................................. .................................................... .................... 7

4.6 Información para el uso general del software ........................................... .......................................... 7
4.7 Información para trámites y tutoriales ............................................... ....................................... 7
4.8 Información sobre comandos de software ........................................... ............................................... 8

4.9 Información sobre mensajes de error y resolución de problemas ....................................... ..................... 8

4.10 Información sobre terminología .................................................. .................................................... ........ 8
4.11 Información sobre fuentes de información relacionadas .................................. .................................... 8

5. Formato de la documentación del usuario del software .................................. .................................................... 9

5.1 Coherencia de terminología y formatos ............................................... ....................................... 9

5.2 Uso de formatos impresos o electrónicos ........................................... .......................................................... 9
5.3 Legibilidad................................................ .................................................... .................................... 10
5.4 Formatos de advertencias, precauciones y notas .................................. .......................................... 10
5.5 Formato de las instrucciones ............................................... .................................................... ............... 10

5.6 Formatos para representar elementos de interfaz de usuario ........................................... .......................... 11

5.7 Formatos de las características de la documentación para acceder a la información .................................. ...... 11
5.8 Formatos de funciones para la navegación........................................... .......................................... 12
5.9 Formatos para ilustraciones .................................................. .................................................... ............. 13

Anexo A (informativo) Bibliografía ............................................... .................................................... .......... 14

Anexo B (informativo) Documentación de usuario del software de indexación .................................. ........................ 15
Índice .................................................. .................................................... .................................................... . dieciséis

Copyright © 2001 IEEE. Todos los derechos reservados. v

Machine Translated by Google
Machine Translated by Google

Estándar IEEE para usuarios de software

Documentación

1. Información general

Esta cláusula presenta el alcance, el propósito, la organización y los posibles usos de esta norma.

1.1 Alcance

Esta norma proporciona los requisitos mínimos para la estructura, el contenido de la información y el formato de la información del usuario.
documentación, incluidos los documentos impresos y electrónicos utilizados en el entorno de trabajo por los usuarios de
sistemas que contienen software. Este estándar se limita al producto de documentación de software y no
incluir los procesos de desarrollo o gestión de la documentación del usuario del software; se aplica al usuario impreso
manuales, ayuda en línea y documentación de referencia del usuario. No se aplica a materiales de cursos especializados.
destinado principalmente para su uso en programas de formación formal.

Esta norma no pretende alentar ni desalentar el uso de documentos impresos o electrónicos (en línea)
medios de documentación, o de cualquier herramienta o metodología particular de desarrollo o gestión de documentación. Los usuarios de
este estándar pueden querer desarrollar un manual de estilo para usar dentro de sus propias organizaciones para
complementar la guía provista en el estándar, o adoptar una guía de estilo reconocida por la industria. Usuarios de
este estándar también puede querer realizar pruebas de usabilidad en la documentación del usuario del software. Los trabajos
enumerados en la bibliografía brindan orientación sobre los procesos de administración, preparación y prueba de la documentación del usuario
(consulte el Anexo A).

1.2 Propósito

Esta revisión proporciona requisitos para la estructura, el contenido de la información y el formato de los documentos impresos y
documentación electrónica. Aborda los intereses de los adquirentes, productores y usuarios de software en los estándares.
para una documentación coherente, completa, precisa y utilizable.

1.3 Organización de la norma

Después de la Cláusula 2, este estándar se organiza de acuerdo con los diferentes aspectos de la documentación del usuario: estructura
(Cláusula 3), contenido de la información (Cláusula 4) y formato (Cláusula 5). En cada cláusula, los requisitos son
independiente de los medios, en la medida de lo posible. Se identifican los requisitos específicos para los medios impresos o electrónicos.
como tal, particularmente en la Cláusula 5. El orden de las cláusulas en este estándar no implica que el usuario del software
la documentación debe desarrollarse en este orden o presentarse al usuario en este orden.

Copyright © 2001 IEEE. Todos los derechos reservados. 1

Machine Translated by Google

IEEE
Norma 1063-2001 ESTÁNDAR IEEE PARA SOFTWARE

1.4 Usos candidatos

La redacción de cada cláusula en esta norma ayuda a aquellos que pretenden reclamar conformidad con la norma.
El término deberá identificar los requisitos obligatorios para reclamar conformidad con esta norma. El término debe
identifica un enfoque que se recomienda, pero no se requiere, para reclamar conformidad con este estándar. los
El término puede identifica un enfoque que está permitido dentro de los límites del estándar, pero no requerido para reclamar
conformidad con esta norma.

Esta norma puede ser incluida o referenciada en contratos o acuerdos similares cuando las partes (llamadas
adquirente y el productor o proveedor) acuerdan que el proveedor entregará la documentación de acuerdo con
el estandar. Este estándar también puede ser adoptado como un estándar interno por un proyecto u organización que
decide producir documentación de acuerdo con la norma. Aunque esta norma está destinada a
documentación de software para usuarios finales, se puede aplicar a la documentación producida para operadores de computadoras
o administradores de sistemas que no sean usuarios finales.

Este estándar está destinado a adaptarse para que solo se apliquen los requisitos necesarios y rentables.
La adaptación puede tomar la forma de especificar enfoques para cumplir con sus requisitos obligatorios, o alterar
sus recomendaciones y enfoques no obligatorios para reflejar el software y la documentación en particular
producto de manera más explícita. Las decisiones de adaptación tomadas por el adquirente deben especificarse en el contrato.

2. Definiciones

A lo largo de este estándar, el término documentación se refiere a la documentación del usuario del software. El uso de la terminología
en esta norma es para facilitar la referencia y no es obligatorio para cumplir con la norma. Para
Para los propósitos de esta norma, se aplican los siguientes términos y definiciones. IEEE 100, The Authoritative Dictionary of IEEE
Standards Terms, Séptima edición [B9]1 , debe ser referenciado para los términos no definidos en este
cláusula.

2.1 acción: Elemento de un paso que realiza un usuario para completar un trámite.

2.2 precaución: aviso en la documentación del usuario del software que indica que realizar alguna acción puede tener consecuencias
no deseadas o indefinidas, como la pérdida de datos o un problema con el equipo. (Ver también: advertencia
y nota.)

2.3 información crítica: Información sobre el uso seguro del software, la seguridad de la información creada
con el software, o la privacidad de la información creada o almacenada con el software.

2.4 conjunto de documentos: una colección de documentación que se ha segmentado en volúmenes o productos identificados por
separado para facilitar su distribución o uso.

2.5 ilustración: Elemento gráfico apartado del cuerpo principal del texto y normalmente citado dentro del cuerpo principal .
texto. En esta norma, el término ilustración se usa como término genérico para tablas, figuras, exhibiciones, capturas de pantalla,
diagramas de flujo, diagramas, dibujos, íconos y otros elementos gráficos.

2.6 modo de instrucción: modo de uso que tiene por objeto enseñar el uso del software en la realización de tareas.

2.7 nota: consejos útiles y otra información que puede ayudar al usuario al enfatizar o complementar
puntos importantes del texto principal. (Ver también: advertencia y precaución).

2.8 procedimiento: Serie ordenada de pasos que sigue un usuario para realizar una o más tareas.

1
Los números entre paréntesis corresponden a los de la bibliografía del Anexo A.

2 Copyright © 2001 IEEE. Todos los derechos reservados.

Machine Translated by Google

IEEE
DOCUMENTACIÓN DEL USUARIO Norma 1063-2001

2.9 modo de referencia: Modo de uso destinado a proporcionar acceso rápido a información específica para usuarios de software que
generalmente están familiarizados con las funciones del software.

2.10 producto de software: uno o más programas de computadora junto con cualquier elemento auxiliar no electrónico, no mecánico,
como documentación y hojas de trabajo, entregado bajo un solo nombre para
uso por otros.

2.11 documentación del usuario del software: cuerpo de material electrónico o impreso que proporciona información a
usuarios de software.

2.12 paso: Un elemento de un procedimiento. Un paso contiene una o más acciones.

2.13 estilo: Conjunto de convenciones editoriales que cubren la gramática, la terminología, la puntuación, el uso de mayúsculas y el diseño
de un documento de usuario de software.

2.14 tutorial: Procedimiento de instrucción en el que el usuario ejerce las funciones del software utilizando datos de muestra suministrados
con el software o la documentación.

2.15 modo de uso: Manera principal en que el expedidor del documento espera que se utilice el documento. Esta
El estándar reconoce dos modos de uso: instructivo y de referencia.

2.16 usuario: Persona que emplea software para realizar una tarea.

2.17 advertencia: aviso en la documentación del usuario del software que indica que realizar alguna acción puede provocar lesiones graves o
consecuencias peligrosas. (Ver también: precaución y nota).

3. Estructura de la documentación del usuario del software

La estructura de la documentación del usuario del software, tanto impresa como electrónica, incluye cómo se organiza en
segmentos y en qué orden se presentan los segmentos. La documentación puede estructurarse en un único
documento o un conjunto de documentos impresos y/o electrónicos. La estructura de la documentación del usuario del software debe ayudar
al usuario a localizar y comprender el contenido de la información. Cuando se establece un documento
se dirigirá a audiencias con necesidades muy diferentes, se utilizará al menos una de las siguientes estructuras:

— Secciones separadas dedicadas a las necesidades de audiencias específicas. Las audiencias y sus necesidades serán
identificadas específicamente en la introducción, permitiendo a cada usuario identificar las secciones de su interés.

— Documentos separados o conjuntos de documentos para cada audiencia específica.

La Tabla 1 enumera los componentes estructurales, de contenido y de formato requeridos y opcionales del documento. Los componentes
pueden disponerse en este orden en la documentación impresa. Los componentes necesarios se incluirán en
documentación del usuario del software a menos que la información no exista o no sea aplicable para un
documento. Por ejemplo, una descripción de convenciones puede no ser aplicable en un documento de descripción general. los
los componentes pueden ser renombrados; por ejemplo, la información sugerida para la introducción podría ir en una sección
etiquetado como "Prefacio".

Copyright © 2001 IEEE. Todos los derechos reservados. 3

Machine Translated by Google

IEEE
Norma 1063-2001 ESTÁNDAR IEEE PARA SOFTWARE

Tabla 1—Componentes de la documentación del usuario del software

Ver
Componente subcláusula ¿Requerido?

Datos de identificación (etiqueta del paquete/portada) 4.3 sí

Tabla de contenido 5.7.1 Sí, en documentos de más de ocho páginas posteriores a

los datos de identificación

Lista de Ilustraciones 5.7.2 Opcional

Introducción 3.2 sí

Información para el uso de la documentación 4.4 sí

Concepto de operaciones 4.5 sí

Procedimientos 4.6, 4.7 Sí (modo instructivo)

Información sobre comandos de software 4.8 Sí (modo de referencia)

Mensajes de error y resolución de problemas 4.9 sí

Glosario 4.10 Sí, si la documentación contiene términos desconocidos

Fuentes de información relacionadas 4.11 Opcional

Funciones de navegación 5.8 sí

Índice 5.7.3 Sí, en documentos de más de 40 páginas

Capacidad de búsqueda 5.7.4 Sí, en documentos electrónicos

3.1 Estructura general de la documentación

Un conjunto de documentos puede constar de uno o más documentos, y cada documento de un conjunto de documentos puede ser uno o
más volúmenes. Por ejemplo, un manual de comando impreso puede tener un volumen que cubre la mitad del
comandos y un segundo volumen que cubre la otra mitad de los comandos.

Los documentos se estructurarán en unidades con contenido único. La documentación bien estructurada hace que la información esté
disponible donde se necesita sin redundancia.

A efectos de esta norma, se utiliza la siguiente nomenclatura no obligatoria para las partes estructurales de
documentación del usuario del software. Un documento impreso está estructurado en unidades lógicas llamadas capítulos, subdivididos
en temas, que pueden subdividirse en subtemas, e imprimirse en unidades físicas denominadas páginas. Un documento electrónico se
estructura en unidades lógicas denominadas temas y se presenta en unidades físicas denominadas páginas o
pantallas Debido a las variaciones entre los dispositivos físicos de visualización, el término pantalla , tal como se utiliza aquí, no se refiere
necesariamente al material que se muestra al usuario en un solo instante, sino a la colección completa de
material disponible mediante simples operaciones de desplazamiento. Cada página o pantalla deberá tener una etiqueta única (por
ejemplo, con un número de página o tema, o nombre o número de pantalla). Cuando se ve o se imprime, cada tema en un
documento electrónico debe ser identificable como perteneciente al documento principal. Por ejemplo, una barra de estado o
encabezado muestra el nombre del documento o archivo.

Los documentos impresos se estructurarán con no más de tres niveles de subdivisión dentro de un capítulo. Para
ejemplo, un subtema numerado 1.2.3.4 estaría en el nivel más bajo de subdivisión. Documentos electrónicos
estarán estructurados de manera que se pueda acceder a la información con no más de tres saltos (enlaces) desde la inicial
página de un tema (sin contar ninguna acción requerida para abrir el documento).

4
Copyright © 2001 IEEE. Todos los derechos reservados.
Machine Translated by Google

IEEE
DOCUMENTACIÓN DEL USUARIO Norma 1063-2001

La estructura de la documentación, la extensión de un capítulo o tema y la cantidad de información presentada en una página o
pantalla (unidad física) dependen de varias consideraciones:

— Acceso a la documentación durante el uso del software

- Cantidad de información
— Familiaridad de la audiencia con la información.
— Limitaciones de los medios
— Modos de uso

La organización de la documentación deberá sustentar su modo de uso (instruccional o de referencia). Cuando un documento contenga
material instructivo y de referencia, ambos deberán estar claramente separados en diferentes
capítulos o temas, o distinguidos por formato dentro del capítulo o tema.

La documentación del modo de instrucción orientado a tareas debe incluir procedimientos estructurados de acuerdo con las necesidades del usuario.
Tareas. Las tareas relacionadas deben agruparse en el mismo capítulo o tema. Los capítulos y temas deben estar organizados
facilitar el aprendizaje al presentar tareas más simples, más comunes o iniciales antes que tareas más complejas, menos utilizadas o
posteriores.

La documentación del modo de referencia debe organizarse para facilitar el acceso aleatorio a unidades individuales de información.
Por ejemplo, una lista de comandos de software o mensajes de error debe ordenarse alfabéticamente.

3.2 Componentes iniciales

Cada documento individual debe estar estructurado para comenzar con datos de identificación (ver 4.3), seguido de una tabla
de contenidos (ver 5.7.1) y una introducción; es decir, la introducción es el primer capítulo o tema del documento. La introducción debe
describir la audiencia prevista, el alcance y el propósito del documento y
incluir una breve descripción general del propósito del software, las funciones y el entorno operativo.

Las introducciones se proporcionarán dentro de un documento para cada capítulo y tema. Las secciones introductorias deben
proporcionarse para cada característica o función principal del software que se está documentando. Las secciones introductorias
proporcionará una descripción general del tema, el propósito de la función y cualquier requisito ambiental,
advertencias, precauciones o requisitos del usuario exclusivos del tema.

3.3 Ubicación de la información crítica

La información crítica debe colocarse en un lugar destacado de la documentación. Advertencias generales o

Las precauciones que se aplican durante el uso del software o la documentación deben aparecer en los componentes iniciales. Las
advertencias y precauciones específicas aparecerán en la misma página o pantalla e inmediatamente antes de la
procedimiento o paso que requiere atención.

4. Contenido de la información de la documentación del usuario del software

Esta cláusula especifica las características de la información contenida en la documentación del usuario (ver 4.1 y 4.2),
incluyendo la integridad y la precisión. Esta cláusula también define la información requerida para su inclusión en el usuario
documentación (ver 4.3 a 4.11). La información requerida en esta cláusula se incluirá en el software
documentación del usuario a menos que la información no exista o no sea aplicable para un documento específico.

El contenido de la documentación está relacionado con su modo de uso. Los usuarios de software necesitan documentos para aprender
sobre el software (modo de instrucción) o para refrescar su memoria al respecto (modo de referencia). Instructivo
los documentos de modo pueden estar orientados a información oa tareas. Los documentos orientados a la información instruyen al
usuario sobre los conceptos y la información técnica necesaria para utilizar correctamente el software (ver 4.5). Tarea orientada

5
Copyright © 2001 IEEE. Todos los derechos reservados.
Machine Translated by Google

IEEE
Norma 1063-2001 ESTÁNDAR IEEE PARA SOFTWARE

los documentos muestran al usuario cómo completar los procedimientos para alcanzar una meta (ver 4.6). La documentación del modo
de referencia puede ser sensible al contexto e integrada en el software, por ejemplo, listas emergentes o desplegables de
valores de datos o comandos aceptables. Ya sea en la documentación instructiva o de referencia, el contenido de la documentación se
puede mejorar mediante la inclusión de ejemplos e ilustraciones.

4.1 Integridad de la información

La documentación deberá proporcionar información instructiva y de referencia completa para todas las funciones críticas del software
(software cuya falla podría tener un impacto en la seguridad o podría causar grandes pérdidas financieras o sociales).
La documentación del modo de instrucción deberá incluir información completa para permitir el desempeño de los
tareas utilizando las funciones del software por parte de los miembros menos experimentados de la audiencia. La documentación del
modo de referencia incluirá todas las instancias de los elementos seleccionados que se están documentando. Por ejemplo, si la referencia
La documentación del modo cubre un subconjunto de comandos de software, debe incluir todos los comandos y mensajes de error
ingresados por el usuario y mostrados por el sistema en ese subconjunto.

4.2 Precisión de la información

La documentación deberá reflejar con precisión las funciones y los resultados de la versión de software aplicable. Si el
la versión anterior de la documentación ya no es precisa, la nueva documentación estará disponible con el software
actualizaciones o mejoras. Las correcciones y actualizaciones de la documentación se pueden proporcionar a través de un nuevo manual, un archivo Léame
archivo o hoja de erratas, o un archivo descargado de un sitio web.

4.3 Contenido de los datos de identificación

La documentación deberá contener datos de identificación únicos. Los datos de identificación incluirán lo siguiente:

a) Título de la documentación
b) Versión de la documentación y fecha de publicación
c) Producto y versión del software
d) Organización emisora

Los datos de identificación aparecerán en una etiqueta del paquete, legible sin abrir el paquete, y en una página de título.
No se requiere una etiqueta de paquete si la página de título es legible sin abrir el paquete. Cada documento en un
conjunto de documentos tendrá una página de título única. Para documentos de una sola página, como tarjetas de referencia rápida, el
los datos de identificación pueden aparecer en la misma página que el resto del documento.

El título del documento debe indicar su naturaleza y alcance y no debe incluir abreviaturas o acrónimos a menos que sean familiares
para la audiencia prevista. Si hay diferentes versiones del software disponibles para
diferentes entornos operativos, la página de título debe especificar los entornos operativos aplicables,
incluidas las versiones de hardware, comunicaciones y sistema operativo. Otra información, incluyendo
Los números de pieza del producto de software o del documento, los números de serie y las restricciones de uso pueden incluirse en la
etiqueta del paquete y en la portada o páginas siguientes. La etiqueta del paquete y las páginas que siguen inmediatamente
la página de título debe incluir avisos de derechos de autor y marcas registradas, restricciones para copiar o distribuir la documentación,
información para contactar a la organización emisora (comentarios del lector), garantías, condiciones contractuales
obligaciones o exenciones de responsabilidad, y advertencias y precauciones generales.

La identificación del documento y del software deberá ser consistente con la gestión de configuración
prácticas de la organización emisora o de la organización adquirente. La información (historial de cambios) se proporcionará en el
conjunto de documentos para documentar la fecha de emisión y el número de versión de la versión actual y cada
versión anterior de la documentación.

6
Copyright © 2001 IEEE. Todos los derechos reservados.
Machine Translated by Google

IEEE
DOCUMENTACIÓN DEL USUARIO Norma 1063-2001

4.4 Información para el uso de la documentación

La documentación deberá incluir información sobre cómo se utilizará (por ejemplo, ayuda sobre ayuda), y una
explicación de la notación (una descripción de formatos y convenciones—ver 5.8). Al menos un documento en un
conjunto de documentos identificará todos los documentos en el conjunto por título y uso previsto, incluidas recomendaciones sobre
qué miembros de la audiencia deben consultar qué secciones de la documentación. En conjuntos de documentos que comprenden
muchos volúmenes o productos, esta información puede proporcionarse en un "hoja de ruta" o guía separada para
el conjunto de documentos. La documentación puede incluir la identificación y discusión de cambios notables de la versión anterior
del conjunto de documentos y el software.

4.5 Concepto de operaciones

La documentación deberá explicar los antecedentes conceptuales para el uso del software, utilizando métodos como
descripción visual o verbal del proceso o flujo de trabajo; o la teoría, justificación, algoritmos o concepto general
de operación. Las explicaciones del concepto de operación deben adaptarse a la familiaridad esperada del
usuarios con cualquier terminología especializada para tareas de usuario y funciones de software. La documentación se relacionará
cada función documentada con el proceso o las tareas generales. La información conceptual puede presentarse en una
sección o inmediatamente anterior a cada procedimiento aplicable.

4.6 Información para el uso general del software

La documentación del modo de instrucción orientado a la tarea debe incluir instrucciones para las actividades de rutina que son
aplicado a varias funciones:

— Instalación y desinstalación del software, si la realiza el usuario

— Orientación para el uso de las características de la interfaz gráfica de usuario (ver 5.6)
— Acceder o iniciar sesión y cerrar sesión en el software
— Navegación por el software para acceder y salir de las funciones
— Operaciones de datos (ingresar, guardar, leer, imprimir, actualizar y eliminar)
— Métodos de cancelación, interrupción y reinicio de operaciones

Estos procedimientos comunes deben presentarse una vez para evitar la redundancia cuando se utilizan en más
funciones complejas.

4.7 Información para trámites y tutoriales

La documentación del modo de instrucción proporciona instrucciones para realizar los procedimientos. Las instrucciones incluirán
información preliminar, pasos de instrucción e información de finalización.

La información preliminar común a varios procedimientos puede agruparse y presentarse una sola vez para evitar la redundancia. La
información preliminar para las instrucciones incluirá lo siguiente:

— Una breve descripción general del propósito del procedimiento y definiciones o explicaciones de los conceptos necesarios no
incluidos en otra parte
— Identificación de las actividades técnicas o administrativas que deben realizarse antes de iniciar la tarea
— Una lista de materiales que el usuario necesitará para completar la tarea, que puede incluir datos, documentos, contraseñas,
software adicional e identificación de controladores, interfaces o protocolos.
— Advertencias, precauciones y notas pertinentes que se aplican a todo el procedimiento

7
Copyright © 2001 IEEE. Todos los derechos reservados.
Machine Translated by Google

IEEE
Norma 1063-2001 ESTÁNDAR IEEE PARA SOFTWARE

Las advertencias, precauciones y notas pertinentes deben preceder inmediatamente a cada paso o grupo de instrucción aplicable.
de pasos Los pasos de instrucción utilizarán el estado de ánimo imperativo para la acción del usuario. Los pasos de instrucción deberán
indicar el resultado esperado o la respuesta del sistema. Los pasos de instrucción incluirán o proporcionarán referencias a
documentación del rango aceptable, longitud máxima y formato aplicable, y unidad de medida de
campos de datos para datos proporcionados por el usuario. Los formatos y valores de datos aceptables se documentan comúnmente a través de
listas emergentes. Los pasos instructivos deben incluir o proporcionar referencias a explicaciones de mensajes de error y
procedimientos de recuperación.

Los pasos de instrucción se presentarán en el orden de ejecución. Los procedimientos alternativos o repetidos deben
estar claramente indicado, para que el usuario pueda determinar qué pasos alternativos o repetidos debe realizar u omitir y
dónde volver a unirse al procedimiento principal.

La información de finalización de las instrucciones deberá indicar cuál es el último paso del procedimiento, cómo el usuario
puede determinar si el procedimiento se ha completado con éxito, y cómo el usuario debe salir de la
procedimiento.

4.8 Información sobre comandos de software

La documentación deberá explicar los formatos y procedimientos para los comandos de software ingresados por el usuario, incluidos
parámetros requeridos, parámetros opcionales, opciones predeterminadas, orden de los comandos y sintaxis. Documentación
puede proporcionarse en el desarrollo y mantenimiento de macros y scripts. La documentación del modo de referencia contendrá una lista de
referencia de todas las palabras o comandos reservados. Los ejemplos deben ilustrar el uso
de comandos La documentación deberá explicar cómo interrumpir y deshacer la operación durante la ejecución de un comando y cómo reiniciarlo,
si es posible. La documentación debe describir cómo reconocer que el comando ha
ejecutado con éxito o terminado anormalmente.

4.9 Información sobre mensajes de error y resolución de problemas

La documentación debe abordar todos los problemas conocidos en el uso del software con suficiente detalle para que el
los usuarios pueden recuperarse de los problemas ellos mismos o informar claramente el problema al soporte técnico
personal. La documentación del modo de referencia incluirá cada mensaje de error con una identificación del
problema, causa probable y acciones correctivas que el usuario debe tomar. Una tarjeta de referencia rápida puede
abordar los mensajes de error remitiendo al usuario a documentación de referencia más detallada. La documentación
sobre la resolución de problemas también incluirá información de contacto para informar problemas con el software o su documentación y sugerir
mejoras.

4.10 Información sobre terminología

La documentación debe incluir un glosario, si es probable que los términos o sus usos específicos en la interfaz de usuario del software o la
documentación no sean familiares para la audiencia. El glosario incluirá una lista alfabética de términos
y definiciones. La documentación que utilice abreviaturas y acrónimos desconocidos para la audiencia incluirá una
lista con definiciones, que pueden integrarse con el glosario. Los términos incluidos en el glosario también deben
definirse en su primera aparición en la documentación impresa. La documentación electrónica puede incluir enlaces
desde términos hasta glosarios o explicaciones en ventanas secundarias.

4.11 Información sobre fuentes de información relacionadas

La documentación puede contener información sobre el acceso a fuentes de información relacionadas, como una bibliografía,
lista de referencias o enlaces a páginas web relacionadas. Las fuentes de información relacionadas y las referencias pueden incluir la
siguiente:

8 Copyright © 2001 IEEE. Todos los derechos reservados.

Machine Translated by Google

IEEE
DOCUMENTACIÓN DEL USUARIO Norma 1063-2001

— Especificaciones de requisitos, especificaciones de diseño y estándares aplicables para el software y el

documentación
— Planes y procedimientos de prueba para el software y la documentación.
— Políticas y procedimientos de gestión de la configuración para el software y la documentación.
— Documentación para el entorno de hardware y software.
— Explicaciones del concepto de operaciones o procesos científicos, técnicos o comerciales incorporados en
El software.

La documentación debe indicar si las referencias contienen requisitos obligatorios o informativos.

material de fondo

5. Formato de la documentación del usuario del software

El formato de la documentación incluye los medios electrónicos o impresos seleccionados y las convenciones de presentación para
elementos estilísticos, tipográficos y gráficos. Esta cláusula especifica formatos para varios componentes de la documentación. El
formato para la documentación del modo de referencia debe ser accesible y utilizable en los usuarios previstos.
ambiente de trabajo El tamaño de la documentación de referencia impresa y encuadernada, o el equipo requerido, el espacio de
almacenamiento electrónico, el software del sistema operativo y los navegadores para acceder a la documentación de referencia en línea.
deberá ser consistente con la capacidad del ambiente de trabajo de los usuarios esperados.

La documentación debe proporcionarse en medios y formatos que permitan su uso por parte de personas con limitaciones visuales,
auditivas u otras limitaciones físicas, si pueden usar el software y realizar las tareas respaldadas por el
software. Los medios y formatos de documentación alternativos para usuarios con limitaciones físicas pueden requerir
software de adaptación especial y equipo no proporcionado con el software del usuario o el software del usuario
documentación.

5.1 Coherencia de terminología y formatos

La documentación deberá usar una terminología consistente en todo un conjunto de documentos para los elementos del usuario.
interfaz, elementos de datos, nombres de campo, funciones, páginas, temas y procesos. Convenciones de formato para
la información destacada de especial importancia, como advertencias, precauciones y notas, se aplicará de forma coherente en todo
el conjunto de documentos. La documentación puede utilizar un formato especial para identificar nuevos o
contenido cambiado. Las convenciones de formato pueden incluir colores, bordes, sangría, espaciado y variaciones de fuente. El
material similar, como conjuntos de instrucciones, se presentará en un formato coherente.

Si la documentación se adapta para su uso en otro entorno operativo, idioma o cultura, un

Se deben usar glosarios y guías de estilo para el texto y las ilustraciones para ayudar a los desarrolladores de documentación y
traductores en el mantenimiento de la coherencia. Se debe considerar la selección de terminología, ejemplos,
gráficos y colores que no son específicos de la cultura, por lo que la documentación se puede adaptar, localizar o editar más fácilmente.
traducido conservando el significado previsto del original.

5.2 Uso de formatos impresos o electrónicos

Se proporcione o no documentación electrónica, la siguiente documentación se presentará en

forma impresa:

— Requisitos de hardware, sistema operativo y software de navegador para el software y el

documentación
— Información de instalación, incluida la información de recuperación y solución de problemas para la instalación
instrucciones
— Instrucciones para iniciar el software

Copyright © 2001 IEEE. Todos los derechos reservados. 9

Machine Translated by Google

IEEE
Norma 1063-2001 ESTÁNDAR IEEE PARA SOFTWARE

— Instrucciones para el acceso a cualquier documentación electrónica

— Información para ponerse en contacto con el soporte técnico o realizar acciones de recuperación disponible para los usuarios

Debe incluirse una descripción de cómo imprimir la documentación electrónica tanto en el documento electrónico como en el
documentación impresa. Se proporcionará un medio para imprimir la documentación en línea para ese software
sistemas diseñados para su uso cuando están conectados a una impresora. El sistema debe incluir funciones de software diseñadas
para permitir la impresión de documentación electrónica.

La documentación en línea estará disponible para su visualización en cualquier momento cuando sea posible la entrada del usuario al software.
El usuario debe poder realizar una función y leer la documentación en línea específica de la función relevante
simultaneamente. El usuario debe poder ver la documentación en línea y navegar al software relacionado
funciones durante las operaciones del sistema.

5.3 Legibilidad

La documentación impresa y electrónica deberá ser legible para el usuario, considerando la distancia entre el usuario
y la documentación en el ambiente de trabajo esperado. La documentación debe usar un estilo de fuente y color
que sea legible contra el fondo esperado (color del papel o color de fondo de la pantalla). La documentación en línea seguirá siendo legible si el
usuario puede ampliar, reducir o remodelar la pantalla o la ventana. Mayúsculas (todas
mayúsculas) no se utilizarán para texto continuo de más de 25 palabras. El texto, incluido el texto de las ilustraciones, no deberá ser inferior a 3
mm (aproximadamente 7,5 puntos).

La documentación en línea debe ser legible en el entorno de trabajo esperado de los usuarios, que incluye la combinación anticipada de monitor
o pantalla de computadora y controladores de gráficos de software. La legibilidad puede verse afectada
por dispositivos de salida (monitores e impresoras) que son monocromáticos, tienen resolución limitada, reproducen colores
de forma diferente, o admiten una gama limitada de colores. Algunos dispositivos de salida pueden aplicar fuentes sustitutas o fuentes especiales.
caracteres si la fuente especificada no está disponible. Distinciones que dependen de más de dos gradaciones de
los colores o tonos de gris pueden no ser visibles. Debido a que algunos usuarios no pueden distinguir entre colores, la documentación debe
proporcionar pistas de texto en lugar de usar colores como el rojo y el verde como la única forma de transmitir
sentido.

5.4 Formatos de advertencias, precauciones y notas

Las advertencias, precauciones y notas deben mostrarse en un formato consistente que sea fácilmente distinguible de
texto ordinario o pasos instructivos. La palabra indicadora (por ejemplo, advertencia, precaución o nota ) precederá a la
texto que lo acompaña. El término nota no debe usarse para identificar peligros. Las advertencias y precauciones se identificarán mediante
símbolos gráficos coherentes y distintos, por ejemplo, un signo de exclamación o un rayo dentro
un triángulo. Una advertencia o precaución debe incluir las siguientes partes:

— Palabra indicadora
— Símbolo gráfico
— Breve descripción del peligro
— Texto instructivo sobre cómo evitar el peligro
— Consecuencias de incurrir en el peligro
— Recursos del usuario por las consecuencias adversas, si las hubiere

5.5 Formato para instrucciones

Los pasos de instrucción deben numerarse consecutivamente. Una convención consistente de numeración o letras debe
establecerse para subpasos o acciones, pasos alternativos y procedimientos repetidos.

10 Copyright © 2001 IEEE. Todos los derechos reservados.

Machine Translated by Google

IEEE
DOCUMENTACIÓN DEL USUARIO Norma 1063-2001

5.6 Formatos para representar elementos de la interfaz de usuario

Elementos de la interfaz gráfica de usuario (GUI) del software, como botones, iconos, cursores variables y punteros; usos especiales de
las teclas del teclado o combinaciones de teclas; y las respuestas del sistema se representarán en
documentación mediante formatos gráficos o tipográficos coherentes, de modo que los distintos elementos se distingan del texto. La
documentación debe incluir una representación del elemento, su propósito y una
explicación de su acción (consecuencia funcional), con ejemplos de instancias operativas reales. En línea
la documentación puede incluir etiquetas de texto emergentes para los elementos de la GUI.

Los formatos de documentación para comandos o códigos ingresados por el usuario deben distinguir claramente entre literales (a ser
entrada exactamente como se muestra) y variables (a ser seleccionadas por el usuario). No se deben utilizar comillas en
representaciones de comandos a menos que el usuario las ingrese literalmente. La documentación debe abordar las variaciones en los
teclados o dispositivos de entrada de datos en el entorno de trabajo esperado de los usuarios.

5.7 Formatos de las características de la documentación para acceder a la información

La documentación deberá contener características para proporcionar acceso a la información, incluida una tabla de contenido; una lista de
figuras, tablas o ilustraciones; un índice; y capacidades de búsqueda electrónica.

5.7.1 Índice

Un índice debe seguir inmediatamente a los datos de identificación (ver 4.3). La tabla de contenido debe enumerar
los encabezamientos de los capítulos o temas de un documento con un punto de acceso para cada uno (su número de página inicial o
un enlace electrónico). Los documentos con menos de ocho páginas después de los datos de identificación pueden omitir la tabla de
contenido.

El índice puede ser completo o simple. Una tabla de contenido completa enumera todos los capítulos o
títulos de temas (encabezados) hasta el tercer nivel. Una tabla de contenido simple incluye solo el primer nivel
encabezados Los documentos con una tabla de contenido simple pueden incluir tablas de contenido completas secundarias que aparecen
al comienzo de cada capítulo o tema, o accesibles a través de ventanas emergentes, listas expandibles o
ventanas secundarias. La documentación electrónica puede mostrar tablas de contenido en formato expandible y plegable.
formatos para proporcionar acceso detallado y de alto nivel a los encabezados sin desplazamiento excesivo. Al menos un volumen
de un conjunto de documentos deberá incluir un índice simple para todos los volúmenes del conjunto.

La tabla de contenido deberá incluir todas las partes de la documentación, incluido el material preliminar que sigue al
índice y contraportada (por ejemplo, apéndices, glosario e índice). Los encabezados de la tabla
Los contenidos serán idénticos en términos de redacción a los del documento, incluidos los números de capítulo o tema. los
El formato de la tabla de contenido distinguirá la jerarquía de los encabezados mediante tipografía o sangría consistentes. En la
documentación impresa, el índice debe enumerar los encabezados en el mismo orden que en el texto.
Para la documentación electrónica, la tabla de contenido debe ordenar los encabezados de acuerdo con la secuencia de navegación,
tarea, tipo de tema u otros criterios lógicos.

5.7.2 Lista de ilustraciones

La documentación debe contener una lista de tablas, una lista de figuras o una lista de ilustraciones (incluidas ambas tablas
y figuras) si el documento contiene más de cinco ilustraciones numeradas y las ilustraciones no son visibles al mismo tiempo que las
referencias en el texto. La lista de ilustraciones incluirá los números de ilustración y
títulos con un punto de acceso para cada uno (como su número de página inicial o un enlace electrónico). Los títulos de la lista.
de tablas, figuras o ilustraciones serán idénticas en redacción a las del documento, incluyendo tabla,
números de figuras o ilustraciones.

Copyright © 2001 IEEE. Todos los derechos reservados. 11

Machine Translated by Google

IEEE
Norma 1063-2001 ESTÁNDAR IEEE PARA SOFTWARE

5.7.3 Índice

Un índice es una lista alfabética de palabras clave, gráficos o conceptos con un punto de acceso para cada uno. Los documentos impresos
de más de 40 páginas deberán incluir un índice, cuyos puntos de acceso pueden ser números de página, números de tema, números de
ilustración o referencias a otra entrada de índice. Los documentos electrónicos de más de 40 temas deberán incluir una herramienta de
búsqueda (ver 5.7.4) o un índice cuyos puntos de acceso sean enlaces electrónicos. El Anexo B proporciona orientación para la indexación
de la documentación del usuario. Una entrada de índice puede hacer referencia cruzada a otra entrada de índice; sin embargo, la entrada
a la que se hace referencia dará un punto de acceso a la documentación y no apuntará a una tercera entrada del índice.

5.7.4 Capacidad de búsqueda

La documentación electrónica proporcionará un método para localizar palabras en el texto. Las capacidades de búsqueda electrónica
pueden incluir la búsqueda de texto completo del documento o conjunto de documentos; buscar palabras en ilustraciones; búsqueda por
palabra clave; encontrar una cadena de texto en el tema actual; una búsqueda booleana; y la restricción de una búsqueda a capítulos,
temas o páginas específicos.

5.8 Formatos para funciones de navegación

Las funciones de navegación incluyen títulos de capítulos y temas; títulos de página o pantalla; números de capítulo, título, página y
pantalla; pestañas; encabezados y pies de página; marcadores; saltos (enlaces); Referencias cruzadas; iconos de navegación; y botones
Se proporcionarán características para la navegación de modo que los usuarios puedan determinar su ubicación dentro del documento
impreso o electrónico y todas las ubicaciones a las que pueden moverse desde su ubicación actual. La documentación deberá incluir
explicaciones de las características de navegación específicas del sistema y del documento.
En la documentación impresa, cada página tendrá un número de página único. En la documentación electrónica, cada página o pantalla
tendrá un identificador único (alfanumérico y/o pie de foto) accesible al usuario. Las funciones de navegación permitirán que los usuarios
de la documentación vayan a las siguientes ubicaciones:

— Atrás, para volver a la sección/página desde la que saltó más recientemente (vinculada)
— Siguiente, siguiente tema/página lógica en la secuencia de temas (si corresponde)
— Página/tema lógico anterior justo antes de la que se está viendo (si corresponde)
— Índice (si lo hay)
— Índice (si lo hay)

Las funciones de navegación utilizarán formatos coherentes para la tipografía, como enlaces, colores o gráficos subrayados para
distinguirlos del texto sin formato. Las funciones de navegación deben permanecer accesibles en una ubicación estática si la documentación
electrónica permite desplazarse por el texto.

Los saltos (enlaces) proporcionarán una indicación clara del destino del enlace. Por ejemplo, utilice "Más sugerencias para solucionar
problemas" en lugar de "Haga clic aquí". Los enlaces deben proporcionar la información que el usuario espera de un salto, en lugar de
requerir un enlace a otro enlace que tenga la información buscada. Si el destino está fuera de la documentación, la documentación debe
proporcionar a los usuarios una forma alternativa de localizar la información, en caso de que se haya roto el vínculo o se haya eliminado el
destino. Los enlaces entre temas relacionados deben ser bidireccionales, de modo que cualquiera que sea el tema al que los usuarios
accedan primero, puedan saltar a la información relacionada del otro tema.

La documentación en modo de referencia electrónica debe ser accesible desde el software que documenta y debe proporcionar un medio
claro para salir de la documentación y volver al software. El software puede estar vinculado a la ayuda en línea, los tutoriales o la
documentación del modo de referencia de varias maneras, como las siguientes:

— A través de un menú de ayuda vinculado a un listado de temas o un punto de entrada al sistema de ayuda
— A través de botones de ayuda en las pantallas del software que brindan información sobre un tema en particular (cuadro de diálogo
y ayuda a nivel de campo)
— Mediante ayuda sensible al contexto y texto emergente (información sobre herramientas)

12 Copyright © 2001 IEEE. Todos los derechos reservados.

Machine Translated by Google

IEEE
DOCUMENTACIÓN DEL USUARIO Norma 1063-2001

5.9 Formatos para ilustraciones

Las ilustraciones que acompañan al texto deben aparecer junto a su primera referencia en el texto, de modo que el texto
asociado y la ilustración se puedan ver simultáneamente. En documentación con más de cinco ilustraciones, cada ilustración
debe tener un número y título únicos (ver 5.7.2). Las ilustraciones informales, a las que se hace referencia una sola vez en el
texto o que no tienen texto, pueden no tener título ni numeración.

El formato de las ilustraciones de contenido similar deberá ser consistente en escala, tamaño de pantalla, fuentes, grosor de
línea y uso del color. En la documentación electrónica, las ilustraciones deben tener un tamaño tal que sean legibles y visibles
en su totalidad, sin desplazarse, en el dispositivo de visualización esperado. Considere simplificar o mostrar solo las
características sobresalientes de un gráfico grande para que sea visible al mismo tiempo sin desplazarse. Las tablas largas
que no caben en una sola página deberán repetir el título de la tabla y los encabezados de columna o fila en cada página o
doble página. Las tablas largas que abarcan varias páginas también deben identificarse con un número de hoja, por ejemplo,
"Tabla 15. Unidades métricas (hoja 2 de 4)".

La documentación destinada tanto a la distribución impresa como electrónica debe estar lógicamente completa, incluidas las
ilustraciones y las referencias a las ilustraciones, en ambos medios. Es posible que se necesiten menos ilustraciones en la
documentación electrónica que permita enlaces a las pantallas reales del software. Las representaciones de los elementos de
la GUI en la documentación deben ser consistentes con la versión del software que se está documentando.

Copyright © 2001 IEEE. Todos los derechos reservados. 13

Machine Translated by Google

IEEE
Norma 1063-2001 ESTÁNDAR IEEE PARA SOFTWARE

Anexo A

(informativo)

Bibliografía
[B1] Brockmann, RJ, Redacción de una mejor documentación informática: del papel al hipertexto, John Wiley & Sons, Nueva
York, 1990.

[B2] Norma británica BS7649:1993, Guía para el diseño y preparación de documentación para usuarios de software de aplicación.

[B3] Norma británica BS7830:1996, Guía para el diseño y preparación de documentación en pantalla para usuarios de software
de aplicación.

[B4] Dumas, JS y Redish, JC, Una guía práctica para las pruebas de usabilidad, rev. ed., Intelecto, 1999.

[B5] Hackos, JT, Gestión de sus proyectos de documentación, John Wiley & Sons, Nueva York, 1990.

[B6] Hackos, JT y Stevens, DM, Estándares para la comunicación en línea: publicación de información para Internet/ World Wide
Web/ Help Systems/ Corporate Internets, John Wiley & Sons, Nueva York, 1997.

[B7] Hackos, JT y Redish, JC, Análisis de usuarios y tareas para el diseño de interfaces, John Wiley & Sons, Nueva York, 1998.

[B8] Horton, W., Designing and Writing Online Documentation: Hypermedia for Self-supported Products, 2.ª ed., John Wiley &
Sons, Nueva York, 1994.

[B9] IEEE 100, The Authoritative Dictionary of IEEE Standards Terms, séptima edición.

[B10] IEEE Std 610.12-1990, Glosario estándar de terminología de ingeniería de software de IEEE.

[B11] IEEE Std 1465-1998, Adopción del estándar IEEE de ISO/IEC 12119:1994 (E) Estándar internacional— Tecnología de la
información—Paquetes de software—Requisitos de calidad y pruebas.

[B12] IEEE/EIA 12207.1-1997, Guía: implementación industrial de la norma internacional ISO/IEC 12207: 1995 (ISO/IEC 12207)
Norma para tecnología de la información: procesos del ciclo de vida del software: datos del ciclo de vida.

[B13] ISO/IEC 15910:1999, Tecnología de la información—Proceso de documentación del usuario del software.

[B14] ISO/IEC TR 9294:1990, Tecnología de la información: Directrices para la gestión de la documentación del software.

[B15] Nagle, JG, Manual para preparar documentos de ingeniería: desde el concepto hasta la finalización, IEEE Press, Nueva
York, 1996.

[B16] Price, J. y Korman, H., Cómo comunicar información técnica: un manual de documentación de software y hardware,
Benjamin/Cummings, Redwood City, CA, 1993.

[B17] Schriver, KA, Dinámica en el diseño de documentos: creación de textos para usuarios, John Wiley & Sons, Nueva York,
1994.

14 Copyright © 2001 IEEE. Todos los derechos reservados.

Machine Translated by Google

IEEE
DOCUMENTACIÓN DEL USUARIO Norma 1063-2001

Anexo B

(informativo)

Documentación del usuario del software de indexación

Un índice es un dispositivo importante de recuperación de información y debe construirse de manera que sea fácil
para que los usuarios localicen la información que buscan. Este anexo proporciona orientación sobre buenas prácticas para indexar
documentación del usuario del software.

Utilice palabras que los usuarios probablemente busquen y enumere todos los temas del documento. La documentación del usuario del software
minuciosamente indexada puede tener de dos a cinco entradas por tema. Indexe el prefacio, los apéndices, las advertencias,
precauciones y notas. En documentos electrónicos, indexe elementos no textuales como gráficos y multimedia.

Evite palabras clave demasiado generales y use términos descriptivos para las entradas, colocando la palabra principal primero. Por ejemplo, para
el encabezado de texto, "Uso del administrador de archivos", use el encabezado de índice, "administrador de archivos, usando". Publicación doble
entradas. Por ejemplo, el tema que aparece como "guardar archivos" y "archivos, guardar" se publica dos veces. Use sinónimos para proporcionar
términos alternativos para el acceso.

Indique la importancia de la información colocando las palabras clave menores debajo de las principales. Divida las entradas que
tener múltiples referencias en el documento en subentradas que indiquen qué aspecto del tema se cubre.
Utilice entradas primarias detalladas en lugar de entradas secundarias o terciarias. Opcionalmente, identifique las referencias de las páginas
principales marcando el número de página en negrita.

Opcionalmente, para conjuntos de documentos, incluya un índice global además de los índices en los volúmenes individuales.
El índice global proporciona a los usuarios los medios para buscar información en un solo índice, en lugar de buscarla en los índices de los
documentos individuales. Proporcione referencias de ubicación para cada entrada que incluya un
abreviatura del título del documento además de los números de página.

Copyright © 2001 IEEE. Todos los derechos reservados. 15

Machine Translated by Google

IEEE
Norma 1063-2001 ESTÁNDAR IEEE PARA SOFTWARE

Índice

abreviaturas, 4.10 acceso

a la información, 5.7 precisión, 4.2
acrónimos, 4.10 acción, 2.1, 4.7
audiencia, Cláusula 3

B
asunto anterior, 5.7.1
bibliografía, marcador del
Anexo A, 5.8

letras mayúsculas, 5.3

precaución, 2.2, 3.3, 4.7, 5.4, capítulo del anexo
B, 3.1 color, 5.3 comando, software, 4.8, 5.6
integridad de la información, 4.1 concepto de
operaciones, cláusula 3, 4.5 consistencia, 5.1
contenido de la documentación, cláusula 4
aviso de copyright, 4.3 función crítica, 4.1
información crítica, 2.3, 3.3 referencia cruzada,
5.8

D
definiciones, componentes
del documento de la cláusula 2, conjunto de
documentos de la cláusula 3, 2.4, cláusula 3, 4.4, anexo B

mi

ambiente. Véase entorno de trabajo, usuarios. Véase entorno operativo. hoja de erratas, mensaje
de error 4.2, cláusula 3, anexo 4.9. Ver ilustración.

F
figura. Ver ilustración. palabra
indicadora, fuente 5.4, pie de
página 5.3, 5.8

dieciséis
Copyright © 2001 IEEE. Todos los derechos reservados.
Machine Translated by Google

IEEE
DOCUMENTACIÓN DEL USUARIO Norma 1063-2001

formato, 5.8
material preliminar,
5.7.1 función, crítica, 4.1

GRAMO

glosario, cláusula 3, 4.10

interfaz gráfica de usuario (GUI), 5.6, 5.9 gris, 5.3
verde, 5.3

H
peligro, 5.4
encabezado,
5.8 encabezado,
5.8 ayuda, 4.4, 5.8

icono, 5.6, 5.8

datos de identificación, Cláusula 3, 3.2, 4.3
ilustración, 2.5, 5.9 ilustraciones, lista de, 5.7.2
índice, Cláusula 3, 5.7, 5.7.3, contenido de
información del Anexo B, Cláusula 4 información
para el uso del documentación, 4.4 información
para el uso del software, 4.6 componentes iniciales, 3.2
modo de instrucción, 2.6, 3.1, 4.7 instrucciones, 4.7
introducción, cláusula 3, 3.2

saltar, 3.1, 5.8

teclado, palabra
clave 5.6, Anexo B

etiqueta, paquete, 4.3

legibilidad, 5.3 niveles
de subdivisión, 3.1 enlace, 3.1,
5.8 lista de ilustraciones,
cláusula 3, 5.7.2 literales, 5.6

17
Copyright © 2001 IEEE. Todos los derechos reservados.
Machine Translated by Google

IEEE
Norma 1063-2001 ESTÁNDAR IEEE PARA SOFTWARE

METRO

modo, uso, 2.15, Cláusula 4

norte

navegación, Cláusula 3, 4.6, 5.8 nota,

2.7, 5.1, 5.4 avisos, derechos de
autor y marca registrada, 4.3

O
formato en línea, Cláusula 5
entorno operativo, 4.3 organización.
Ver estructura.

PAGS

etiqueta del paquete,

4.3 página, 3.1 número
de página, 5.8 prefacio,
cláusula 3 impresión,
5.2 resolución de
problemas, 4.9 procedimiento,
2.8, cláusula 3, 3.1, 4.7 propósito, 1.2

R
rojo, 5.3
modo de referencia, 2.9, 3.1, Cláusula 4, 4.1, 4.8, 4.9, Cláusula 5, 5.8 fuentes
de información relacionadas, Cláusula 3, 4.11 restricciones, 4.3

alcance, 1.1
pantalla, 3.1
capacidad de búsqueda, Cláusula 3, 5.7.4
tamaño de la documentación, Cláusula 5
comandos de software, Cláusula 3, 3.1, 4.8
documentación del usuario del software, 2.11
paso, 2.12 pasos, instructivo, 4.7, 5.4, 5.5 pasos,
numerados , 5.5 estructura, cláusula 3 estilo,
2.13 subdivisión, niveles de, 3.1

18
Copyright © 2001 IEEE. Todos los derechos reservados.
Machine Translated by Google

IEEE
DOCUMENTACIÓN DEL USUARIO Norma 1063-2001

pestaña,
tabla 5.8. Ver ilustración.
tabla de contenido, Cláusula 3, 3.2, 5.7.1
sastrería, 1.4 orientado a tareas. Ver modo
instructivo. soporte técnico, 5.2 terminología, 5.1

teoría de operaciones. Ver concepto de

operaciones. título, 5.7.1, 5.7.2, 5.8 página de
título, cláusula 3, 4.3 título, ilustración, 5.9 tema, 3.1, 3.2 aviso
de marca registrada, 4.3 tutorial, 2.14, 4.7

tu

actualizaciones,
4.2 modo de uso, 2.15, Cláusula 4
uso del estándar, Cláusula 1
usuario, 2.16 elemento de interfaz
de usuario, 5.6

variables, 5.6

advertencia, 2.17, 3.2, 3.3, 4.3, 4.7, 5.1, 5.4, Anexo B entorno de
trabajo, usuarios, Cláusula 5, 5.6

Copyright © 2001 IEEE. Todos los derechos reservados.

19