¿Cómo clasificar la información en la documentación del usuario final?

7

Uno de los mejores documentos que he leído es el TeXbook de Donald Knuth, el manual del sistema de composición tipográfica TeX , y lo usé en mi primer análisis .

Por lo que puedo decir, el tipo de información transmitida por la documentación se divide en tres categorías: receta, referencia y conocimiento experto que A continuación describo.

¿Qué categorías me faltan?

Receta

Una receta responde a una pregunta como "¿Cómo resuelvo ese problema con este software?" y vincula el mundo de problemas con características del software. Capítulos 3, 7 y 8 en el TeXbook responda preguntas como "¿Cómo ejecuto TeX?" o "¿Cómo escribo texto?" y proporcione recetas al usuario. Otros paquetes de software a menudo contienen procedimientos de instalación o copia de seguridad que se incluyen en esta categoría.

Referencia

Una referencia documenta todos los detalles necesarios en algún software. Es útil para el usuario saber que "esta característica es útil para resolver ese problema" y querer saber si puede parametrizar "esta característica" para resolver un problema cercano. También es útil para solucionar problemas del software cuando da resultados inesperados. El capítulo 14 "Cómo TeX divide los párrafos en líneas" en el TeXbook es un ejemplo de un texto de referencia. Las páginas de manual de UNIX casi siempre pertenecen a esta categoría.

Conocimiento experto

El conocimiento experto relacionado con el problema resuelto por el software también pertenece a la documentación del software. Las razones para esto son al menos:

  1. Los usuarios no son expertos en el área donde el software es útil.

  2. Los expertos usan diferentes terminologías y metodologías para describir o resolver problemas.

Para 1. los matemáticos que leen el TeXbook también aprenden los conceptos básicos de diseño y diseño: se dan cuenta de que existe un conocimiento estructurado en esta área y aprenden los nombres de Los conceptos básicos involucrados, para que puedan expresar los problemas y obtener ayuda. Para 2. es útil para "corregir la notación" en la documentación del software y esto se hace mejor proporcionando información de alto nivel o de fondo.

Por lo tanto, el conocimiento experto contenido en la documentación del usuario vincula la organización conceptual del problema como lo conocen los diseñadores de software con la organización conceptual del problema como lo conocen los usuarios del software.

    
pregunta Michael Le Barbier Grünewald 24.11.2013 - 18:06

4 respuestas

3

Creo que has hecho un muy buen trabajo al resumir la mayoría de los tipos de documentación en esas tres categorías. Me gustaría añadir dos más:

Conocimiento de principiantes / Bootstrapping

Puedes clasificar esto en Recetas, pero creo que es lo suficientemente diferente como para merecer su propia categoría. Una receta ya asume un conocimiento básico del sistema. Escribir una receta para alimentos ya supone un conocimiento básico del dominio de cocción: ya debe saber qué es una cucharadita (si está utilizando ese extraño sistema de medidas. :)), cómo usar un horno, microondas, etc.

Para alguien que nunca ha cocinado o hecho alimentos en su vida, querrá una introducción suave a todo el sistema, mostrándoles lo que pueden hacer y dándoles pequeños trocitos de frescura en el camino para mantenerlos interesados.

Lo mismo se aplica a la documentación. Un principiante tirará rápidamente un libro de recetas, ya que no tienen suficiente conocimiento del dominio para apreciar las recetas. Por lo tanto, necesitan algún conocimiento de principiante, o bootstrapping. Aquí hay algunos puntos sobre este formato de documentación:

  • Muy básico, asegurándose de explicar cada posible término desconocido. Esto puede ser frustrante para algunos usuarios, pero es esencial para educar a cualquiera que esté mirando la documentación.
  • Muchos ejemplos pequeños para mantener al usuario interesado. Estas no son recetas, per se, pero son pequeñas cosas para mantener al principiante interesado, sabiendo que este producto hace cosas geniales
  • Muchos enlaces a otros lugares en la documentación (Recetas, Conocimiento experto, etc.) donde pueden obtener más información sobre algunos de los conceptos que se están discutiendo
  • Lo suficientemente corto como para ser fácilmente digerido. Nadie quiere leer una novela introductoria de 300 páginas

Marketing

Se podría argumentar que esto no es realmente "documentación", pero a menudo se incluye en la documentación. Estas son descripciones de "por qué nuestro producto es tan impresionante que debería usarlo". Es una descripción larga de cómo el producto supera a la competencia. Esto es menos frecuente en el software de código abierto, pero lo ves todo el tiempo en software comercial.

    
respondido por el dsw88 06.12.2013 - 00:44
0

Algo de esto varía si está documentando software o hardware, pero hay posibilidades:

  1. Tutorial (no muy similar a lo que se llama Receta, depende de la situación). Pero al menos un tipo breve de "Hola Mundo", y quizás más. Algunas personas aprenden mejor de los ejemplos. Otros simplemente giran a la derecha a la referencia
  2. Instalación / encender la maldita cosa
  3. Desinstalación / desactivación de la cosa desactivada
  4. Interactuar con otros "estándares". ¿Cómo funciona este gizmo con Spring, XML, USB, Roku, LTE, CloudServices, etc. ¿Existe un complemento de Eclipse?
  5. Peligros / Advertencias / Requisitos / Gotchas. No lo use bajo el agua, funciona, pero ciertas opciones están deshabilitadas en Windows RT, requiere Java 6 o superior, no funciona con IE6, no lo hemos probado en Android 2.2 y versiones anteriores, etc.
  6. Preguntas frecuentes, más un enlace a cualquier ayuda en línea
  7. Avisos legales (si es necesario, espero que pueda evitarlos) Las partes tienen licencia de FooBar Corporation, las partes son GNU, no para uso en diagnósticos, etc ...
  8. Glosario (robé esto del comentario de @ Marco)
respondido por el user949300 05.12.2013 - 21:44
0

Creo que el Tutorial como categoría es digno de distinción de las categorías enumeradas. Un tutorial no es una receta como la has descrito porque no es necesariamente un "cómo". Podría ser una combinación de "cómo", "por qué" y "qué" se utiliza para facilitar la comprensión de otros elementos. Una receta es simplemente "cómo" y está sola, mientras que un tutorial enseña un elemento que puede ser completamente abstracto y solo de uso en combinación con otros elementos. De hecho, uno podría incluso considerar una Receta como una subcategoría de Tutorial.

    
respondido por el James World 06.12.2013 - 00:04
0

Creo que deberías agregar una categoría " Indexación ". Eso describe el mecanismo para reunir toda la otra información a través de etiquetas e hipervínculos para que se pueda acceder a ella de manera sensible al contexto desde la aplicación y desde un índice dentro de la aplicación. Si la información no se encuentra fácilmente, los usuarios irán a Google y omitirán la documentación.

    
respondido por el Turnkey 06.12.2013 - 01:02

Lea otras preguntas en las etiquetas