¿Por qué la documentación de los productos tecnológicos es tan difícil de usar? (en el punto de vista del usuario)

Hoy en día, nuestra documentación de herramientas de desarrollo es difícil de usar y tendemos a encontrar la solución en otras fuentes, como Youtube, problemas de GitHub o publicaciones de blog. Su contenido puede quedarse atrás fácilmente o el punto clave no se ha mencionado en absoluto. Considero que este tema es un problema emergente que debemos alternar lo antes posible, y creo que primero se deben resolver dos problemas importantes. (En el punto de vista del usuario)

• La documentación es demasiado difícil de contribuir a
  • La documentación fácilmente se vuelve obsoleta. La gente tiende a escribir una publicación de blog en lugar de contribuir a un documento porque requiere mucho esfuerzo adicional sin los incentivos correspondientes.
• El contexto está agrupado

  • La documentación en sí apenas se conecta con otros recursos. El contexto que hace una buena documentación está agrupado.

    
    

En este artículo, me gustaría presentar dos conceptos sobre la documentación que creo que son problemáticos y luego expandirlos a 3 puntos de reflexión para resolver estos dos problemas.

En primer lugar, recuerde alguna documentación que haya visitado recientemente y únase a mí con la explicación a continuación. Me gustaría tomar Next.js como ejemplo, que actualmente es mi documentación más visitada. Comencemos con la página "Cómo empezar".

https://nextjs.org/docs/primeros pasos

La documentación de Nextjs tiene una estructura que es popular a través de varios productos, permítanme llamar a esta estructura "Estructura de listado aislado". La razón por la que los llamo aislados es que los mantienen principalmente las personas detrás de Next.js (aunque son de código abierto).

Además, me gustaría concluir la mentalidad detrás de esta documentación como "punto de viñeta del propietario".

Viñeta del propietario

La razón por la que lo llamo "viñeta del propietario" es que el propietario del producto suele realizar el proceso de generación de documentación. Al comienzo de un producto, nadie tiene una mejor comprensión que el propietario. Los propietarios son la mejor persona para mantener la documentación adecuada para sus consumidores y mantenedores.

Pero después de un tiempo, el producto recibe mucho amor y comienza a construir la comunidad. Cada vez es más difícil hacer un seguimiento de los casos de esquina y los errores. Los propietarios tienen que ponerse al día con los nuevos compromisos y resolver problemas a diario, por otro lado, tienen que explicar los nuevos diseños y advertencias y proporcionar información a los recién llegados para superar estos problemas. La carga está aumentando drásticamente.

No todos los productos pueden ponerse al día, el contenido comienza a quedarse atrás y algunas soluciones pueden existir en las publicaciones de blog de otros, las respuestas de StackOverflow, los problemas de GitHub o las discusiones. Un usuario necesita conectar estas soluciones con los motores de búsqueda, a veces la solución en la documentación es incluso incorrecta.

Estructura de listado aislado

La estructura de lista aislada es muy común, en comercio electrónico, en sitios web de propósito general, en su teléfono y en la documentación. Está en todas partes.

La estructura es en su mayoría arbitraria y obstinada y proviene de la mentalidad del "punto de viñeta del propietario", debido a que el propietario primero tiene que idear el árbol de la estructura, en el orden que considere más adecuado para su cliente.

La estructura de lista aislada es una espada de doble filo: para ser claros, no estoy totalmente en contra de esta estructura, es realmente útil en un contexto general. Por ejemplo, es bueno para la exploración inicial y, si está familiarizado con el documento, le resultará bastante fácil encontrar la información que desea.

Pero por otro lado, es una estructura fija, es difícil que la estructura evolucione y cada vez que el mantenedor quiere agregar algo más, es difícil encontrar un lugar apropiado si el propietario no lo pensó bien desde el principio. Además de eso, los usuarios no tienen otra opción que explorar su documentación. Tienen una sola ruta y no es suficiente.

Imagine una estructura dinámica, como un gráfico dirigido por fuerza (algo como Obsidian puede lograr o un diagrama de árbol, puede encontrar muchos ejemplos en su sección de publicación [^1]). No estoy diciendo que los gráficos dirigidos por fuerza o los diagramas de árbol sean mejores que las estructuras de listas aisladas. Lo que quiero es animar a todos a que no piensen de una "manera listada" sino de una "manera más dinámica", para que las personas puedan elegir lo que mejor se adapte a sus necesidades. Pueden usar diagramas de árbol para explorar la estructura y usar el gráfico dirigido por fuerza para reconocer la conexión entre los temas. O podríamos idear una nueva estructura desde cero que pueda resolver algunos de estos problemas.

En combinación, la mentalidad y la estructura conducen al problema que creo que es problemático, que se enumera a continuación.

La documentación es demasiado difícil de contribuir a

En combinación con la mentalidad arbitraria del "punto de viñeta del propietario" y la "estructura de lista aislada", lo que tenemos es que la documentación actual solo puede ser mantenida adecuadamente por el propietario, no hay otra manera fácil de contribuir a la documentación. El problema es doble.

En primer lugar, basado en la mentalidad de "la viñeta del propietario", el autor no quiere que una persona sin experiencia arruine su documentación y es bastante difícil igualar el tono de la documentación si no pasa mucho tiempo alineado con sus mantenedores.

En segundo lugar, su usuario no tiene ningún incentivo para contribuir con la documentación, a la gente le encanta su producto, pero si no obtienen ningún crédito dentro de la construcción del documento o alguna propiedad hacia alguna página de documentación, no hay incentivo.

Puede argumentar que pueden publicar un problema y explicar su sugerencia, pero el problema persiste. La sensación de aportar es muy simultánea, es como la sensación de comprar algo. Imagine un mundo paralelo, aquí, si quiere comprar algo, debe escribir 200 palabras para describir por qué quiere comprar estas cosas y cuál es el beneficio para la comunidad.

No hay necesidad de impedir que las personas aporten documentación con la burocracia. Necesitamos idear otra estructura que pueda seguir siendo la autoridad de la documentación y beneficiar la contribución simultánea al mismo tiempo.

El contexto está agrupado

El material de una buena documentación no es solo la documentación en sí, sino las discusiones, los problemas, las publicaciones de blog relacionadas y los videos correspondientes. Llamaré a estos materiales "Contextos".

Hasta hace poco tendíamos a almacenar estos contextos de forma distribuida. Un proyecto de código abierto regular almacena su discusión en una discusión de GitHub o en un foro de discurso, sus casos de uso en sitios web de productos, problemas directamente en los problemas de GitHub y un sitio web de documentación autohospedado en otro lugar. Además de eso, hay una gran cantidad de contenido generado por la comunidad en YouTube y publicaciones de blogs personales.

En realidad, el contexto de un producto se agrupa. No tendrán interconexión entre sí. Puede haber una discusión sobre la solución al error específico, pero no hay un enlace inverso en la sección de documentación que menciona esta solución. Lamentablemente, tenemos que lidiar con la realidad de que el enlace bidireccional no es lo que Internet actual es capaz de hacer.

El contexto agrupado es volátil

Imagine una situación en la que ingresa la documentación del producto y descubre rápidamente que la documentación no proporciona una solución, más tarde encuentra una solución viable en la publicación del blog de otra persona.

En este momento, con la documentación actual, no hay otra forma de recordar a otros desarrolladores que pueden resolver el mismo problema con este método descrito en la publicación del blog, no puede agregar una referencia a la documentación. Lo que puede hacer es abrir un problema (si es de código abierto) o abrir una discusión en un foro para recordarle a la gente sobre esta solución que pronto se verá inundada por otro contenido.

Cada solución útil en cualquier contexto debe ser resistente a la avalancha de información que tenemos en este momento. Tienen que unirse a este campo de batalla sin punto de anclaje además de los motores de búsqueda.

La lista impresionante [^2] es una buena idea, proporciona una manera de dejar que los buenos contenidos permanezcan, pero tienen el mismo problema con la "estructura de lista aislada" y la mentalidad de "viñeta del propietario".

Si la situación sigue como está...

La consecuencia inmediata de estos problemas será que la “Documentación” se deteriorará con el tiempo. Puede echar un vistazo a la documentación de algún gigante tecnológico, incluida la documentación de los servicios web de Amazon o la documentación de la nube de Google, todos son abrumadores y difíciles de leer.

La peor sensación es que está atascado en un problema específico que no puede encontrar en la documentación ni en ningún otro lugar. Nos enfrentaremos más a este tipo de situaciones si la estructura de nuestra documentación no puede alinearse con el alcance del producto que utilizamos.

Puede parecer abrumador idear un nuevo tipo de estructura para superar estos problemas en primer lugar. Pero mira de cerca, podríamos separar los problemas generales en 3 preguntas para hacernos.

• ¿Cómo alentar a los usuarios a que contribuyan a la documentación y no interfieran con el propósito general del documento? ¿Podemos tener una experiencia más interactiva para la documentación? ¿Puede un usuario contribuir directamente a la documentación sin salir de la página?

• ¿Cómo reunir el contexto para una mejor experiencia de búsqueda que no dependa de soluciones de búsqueda externas y traiga a colación la interconectividad de cada contexto a lo largo del camino?

• ¿Cómo experimentar con una nueva estructura que pueda beneficiar la experiencia del usuario y repetirla con el tiempo, o incluso dejar que los usuarios la elijan libremente?

  
  

https://twitter.com/EiffelFly

[^1]: página de publicación de Obsidian [^2]: sindresorhus/awesome