Spanish

Documentación Del Software De la EscrituraBynum/Peterson
Capítulo 4 – El escribir a la ayuda – Referencia

Donde el capítulo 3 trató la documentación de proceso de la escritura (escritura a la guía), el capítulo 4 se centra en la documentación de la referencia de la escritura. La aserción de It’s Barker’s que los manuales de referencia están engranados hacia los utilizadores que son peritos en usar el software y necesita solamente ir al material de referencia para las respuestas en situaciones complicadas. Él dice que los documentos de la referencia contienen generalmente “how muy pequeño to” a la información. Su función es dirigir al utilizador sobre un cañizo y permitir que him/her continúe encendido con una tarea.La documentación de la referencia (o ayuda) puede tomar muchas diversas formas, incluyendo:descripciones del comando del §descripciones del menú del §listas del § de definicionesdescripciones de la función del §ejemplos del §mensajes de error del §Barker promueve el uso de las cinco guías de consulta siguientes de desarrollar los materiales de referencia eficaces:1. Elija la forma derecha de referenciaBarker indica que los usuarios experimentados que van a los materiales de referencia están buscando generalmente una respuesta rápida a una pregunta o a un problema específica. Hay varios formatos estándares que se prestan a diverso scenarios—appendices, a los ficheros del readme, a las ayudas de trabajo, y a los flipcards. Estas convenciones permiten que un utilizador experimentado del software sepa dónde esperar encontrar la información que necesitan.2. Decida qué incluirCuando escribir a documentación de la referencia una persona debe decidir a qué asuntos para incluir, por ejemplo comandos, elementos del interfaz, y/o definiciones de términos.3. Establezca un modelo“Recognition con regularity” describe esta guía de consulta. Un documento acertado de la referencia relanza los modelos constantes que proporcionan a familiaridad a los utilizadores.4. Ordene La Sección De la ReferenciaLa documentación de la ayuda requiere tomar decisiones en la pedido del material será presentada. Hay dos opciones de organización básicas: alfabético y menu'-por-menu'. Barker dice que hay una ventaja a usar el formato del menu'-por-menu'.5. Muestre cómo utilizar la sección de la referenciaSi los utilizadores son familiares con la diversa documentación de la ayuda del formato pueden tomar, las instrucciones no son generalmente necesarios. Sin embargo, si se combinan los formatos múltiples, una sección introductoria podría ser beneficiosa.
Fijado por Anne

Writing Software Documentation
Bynum/Peterson
Chapter 4 – Writing to Support – Reference

Where Chapter 3 addressed writing process documentation (Writing to Guide), Chapter 4 focuses on writing reference documentation. It’s Barker’s assertion that reference manuals are geared toward users who are adept at using the software and only need to go to the reference material for answers in complicated situations. He says that reference documents usually contain very little “how to” to information. Their function is to direct the user over a hurdle and allow him/her to continue on with a task.

Reference (or support) documentation can take many different forms, including:
§ Command descriptions
§ Menu overviews
§ Lists of definitions
§ Function descriptions
§ Examples
§ Error messages

Barker promotes the use of the following five guidelines to develop effective reference materials:
1. Choose the Right Form of Reference
Barker states that advanced users who go to reference materials are usually looking for a quick answer to a specific question or problem. There are several standard formats that lend themselves to different scenarios—appendices, readme files, job aids, and flipcards. These conventions allow an experienced software user to know where to expect to find the information they need.
2. Decide What to Include
When writing reference documentation a person must decide which topics to include, such as commands, interface elements, and/or definitions of terms.
3. Establish a Pattern
“Recognition through regularity” describes this guideline. A successful reference document repeats consistent patterns that provide familiarity to users.
4. Organize Reference Section
Support documentation requires making decisions on the order of material will be presented. There are two basic organizational options: alphabetical and menu-by-menu. Barker says that there is an advantage to using the menu-by-menu format.
5. Show How to Use the Reference Section
If users are familiar with the different format support documentation can take, instructions are usually not needed. However, if multiple formats are combined, an introductory section could be beneficial.