Buenas referencias para ejemplos de documentación para el usuario final y asesoramiento [cerrado]

10

Nuestro software interno se ha utilizado para muchos usuarios y el departamento de capacitación nos solicitó algunos consejos sobre el formato de documentación del usuario final.

¿Alguien sabe dónde puedo encontrar buenos ejemplos de documentación para el usuario final del software que un departamento de capacitación pueda usar como inspiración o algún sitio con buenos consejos?

Esto es similar a esta pregunta, sin embargo, estoy buscando documentación de usuario final para uso de usuarios no técnicos.

Juan
fuente
1
"¿Dónde puedo encontrar buenos ejemplos de documentación para el usuario final del software?" Paso 1. Compre algún software. Paso 2. Lee la documentación. ¿Qué le impide recoger la documentación del software existente que ya está usando? Creo que la mayoría de los paquetes de usuario final tienen la documentación completa en línea. ¿Qué le impide leer la documentación de Microsoft para su Office Suite?
S.Lott
Creo que la mayor parte de la documentación que he leído está escrita de una manera que no es atractiva para leer, y la mayoría de los libros que tengo generalmente están relacionados con la programación dirigida al público técnico. ¿Ves cuándo alguien leyó por última vez el manual de Microsoft? Por lo tanto, estaba buscando algunos ejemplos inspiradores.
John
Hmm, interesante q.
Torre
@ John: "la mayor parte de la documentación". Bueno. Entonces, después de descartar "la mayoría", ¿qué queda? No sabemos por qué está rechazando parte de la documentación más utilizada en el planeta como "no atractiva para leer". Puede ampliar su lista de quejas y agregar su breve lista personal de ejemplos de documentación de software que no está excluida por su prueba de "no es atractivo leer". No lo conocemos muy bien, por lo que no podemos adivinar por qué quiere decir "no atractivo para leer".
S.Lott
2
Tengamos cuidado de no requerir preguntas con criterios tan específicos de lo que es "bueno" que se convierte en localizado y no aplicable a la mayoría de las personas. No me interesan los esquemas de color.
JeffO

Respuestas:

1

Es posible que desee comenzar entrevistando a sus usuarios internos sobre el software y averiguar qué tipo de información les gustaría saber.

Gran parte de la documentación que he escrito sobre software ha tenido en mente a una o varias audiencias. Su departamento de capacitación probablemente se beneficiaría de un esqueleto de temas (como un TOC). Entonces, podría discutir qué temas son relevantes y cuáles son irrelevantes para sus objetivos de capacitación.

Algunos de los temas podrían cubrir:

  1. Público objetivo)
  2. Requerimientos técnicos
  3. Cómo instalar (si corresponde)
  4. Proceso (es decir, ¿qué función comercial realiza el software?)
  5. Conjunto de características (¿qué características tiene el software?)
    • Podría tener un enfoque basado en tareas para esto, por ejemplo, Agregar un usuario o Agregar un documento
    • Podría tener un enfoque basado en objetos, por ejemplo, usuarios, roles
    • Podría tener un enfoque basado en menús, por ejemplo, menú Archivo, Ver menú
  6. Por último, posiblemente una sección de Próximas funciones y preguntas frecuentes podría actuar como un depósito de conocimiento cada vez mayor de su producto.

Trate de anticipar cómo sus usuarios finales usan su software, basándose en su conocimiento de desarrollarlo, su conocimiento de lo que hace y también en (con suerte) sus entrevistas con los usuarios finales.

Lo que es más importante, intente hacer la documentación que desea leer, use nombres de ejemplo divertidos para demostrar y use muchas capturas de pantalla anotadas.

Espero que esto ayude

funkymushroom
fuente
2

He leído varias "Guías para el usuario final", y escribí una, y creo que hay muchos elementos que mejoran su efectividad:

  • Muestra con imágenes cómo se emite algún comando o se realiza alguna acción (capturas de pantalla, por ejemplo).
  • Concéntrese en la necesidad de hacer algo y la forma de hacerlo. Manténgase alejado de las descripciones técnicas sobre cuán optimizada se realiza esa acción, por ejemplo.
  • Una vez que puse un diagrama de flujo que describía los módulos, el software se dividió y recibí comentarios de que no era muy útil.
  • Intente prever los posibles problemas que pueda tener un usuario, para que su sección Solución de problemas sea ​​útil. También debe probar su programa con usuarios que no estuvieron involucrados en su desarrollo, incluso con sus compañeros de trabajo que trabajaron en otros proyectos.
  • Evita las descripciones aburridas. Cualquier información adicional se puede poner en un apéndice o algo así.

Espero que esto te sea útil.

Nicolás
fuente
1

Mencionas que se usará para el entrenamiento.

Si está buscando un documento de capacitación en lugar de un documento de referencia, mi sitio favorito es el tutorial de Joel Spolsky sobre Mercurial aquí .

  1. Presentación simple y limpia. Es agradable de ver.
  2. Autoritario, pero personal en tono. Se siente como si estuvieras en una gran conferencia universitaria.
  3. Imágenes simples, no una gran cantidad de capturas de pantalla reales. Lea El dorso de la servilleta para saber por qué funciona esto.

Si tu documento de entrenamiento fuera 1/2 tan genial como el tutorial Mercurial de Joel, lo leería. Pero necesita a alguien con a) pasión por la escritura yb) una increíble profundidad de conocimiento para lograrlo, incluso si pudiera copiar los 3 puntos anteriores. Espero que funcione.

MikeRand
fuente
0

No sé si esto posiblemente se adapte a sus necesidades, pero existen sistemas que se utilizan para la documentación técnica de Sphinx, uno que viene a mi mente que facilita la creación de una documentación en línea. ¿Podría usarse algo como esto para lo que le interesa?

También me encontré con ReadTheDocs, que hace casi lo mismo pero es una solución alojada.

Piper Merriam
fuente
0

Echa un vistazo a la Sociedad de Comunicación Técnica (STC) . Muchos de sus ganadores de premios escribieron una producción que generalmente está disponible. También pueden tener muestras disponibles. Convertirse en miembro también proporcionará acceso a una mayor cantidad de información.

Jim Rush
fuente