Nuevo plugin de documentación en desarrollo

Anuncios
,
1

Hemos puesto recientemente nuestro nuevo plugin de documentación a disposición para pruebas y comentarios. Este plugin está diseñado para mejorar la navegación y accesibilidad de la documentación alojada en Discourse, proporcionando una experiencia más accesible y amigable para todos los usuarios. Tenga en cuenta que este plugin todavía está en desarrollo.

El desarrollo de este plugin se deriva de nuestro esfuerzo continuo para mejorar la documentación, que ya ha sido mejorado por una nueva barra lateral. El trabajo en la barra lateral sentó las bases para una experiencia de documentación mucho mejorada, y el nuevo plugin se basa incrementalmente en ese trabajo.

:boom: El nuevo plugin en acción

El plugin está actualmente activo y potencia la documentación en nuestra documentación oficial de Discourse. Le invitamos a explorar sus características y compartir sus experiencias con nosotros. Sus comentarios son invaluables para ayudarnos a refinar y mejorar el plugin.

Las características principales incluidas en el nuevo plugin son:

  • Configuraciones para definir qué categorías se utilizan para la documentación
  • Una nueva barra lateral de documentación poblada por temas de índice dentro de cada categoría
  • Dos nuevos informes para ayudar a mantener la integridad y precisión de los temas de índice

Con más en desarrollo a medida que mejoramos continuamente las características disponibles.

El nuevo plugin está disponible para descargar e instalar hoy mismo: Discourse Doc Categories

:electric_plug: Transición desde el plugin Discourse Docs

A medida que innovamos y avanzamos, retiraremos nuestro antiguo plugin Discourse Docs. Sin embargo, puede estar seguro de que continuaremos brindándole soporte hasta que el nuevo plugin esté completamente listo para un lanzamiento generalizado. También nos hemos asegurado de que el nuevo plugin redirija las URL del plugin antiguo, por lo que el cambio no resultará en ningún enlace roto.

Tenga en cuenta que el nuevo plugin todavía se encuentra en sus etapas experimentales. Si bien nuestro objetivo es proporcionar una experiencia fluida, puede haber algunas áreas que requieran una mayor mejora. Sus comentarios constructivos serán cruciales para su éxito.

:speaking_head: Háganos saber lo que piensa

Agradeceríamos sus pensamientos, experiencias y comentarios. No dude en compartir sus experiencias y cualquier idea que recopile al usar el nuevo plugin de documentación, ya sea navegando por la documentación en Meta o instalando el plugin en su propio sitio.

Nuestro objetivo es dar forma a una mejor experiencia de documentación para toda la comunidad de Discourse, ¡así que todos los comentarios son bienvenidos!

Detalles completos del plugin disponibles aquí:

13 Me gusta
2

Alguien necesita actualizar el readme. Y tal vez actualizar las reglas de lint para evitar que esto suceda, aunque hay un problema de huevo/gallina.

También podría ser genial para usar Discourse como un LMS. Para eso, sería bueno poder cambiar qué categoría era una categoría de documentación, aunque hay una buena posibilidad de que simplemente usar permisos para dar a los usuarios acceso a ciertas categorías sea suficiente para que funcione.

8 Me gusta
3

Buena captura de la URL; acabo de enviar una PR para añadirla.

¡Suena como un caso de uso interesante para esto, y puedo ver cómo funcionaría bastante bien!

6 Me gusta
4

Esta es una mejora fantástica con respecto al plugin original de Docs/base de conocimiento. Hasta ahora parece muy fácil de usar.

Probar en Meta es definitivamente una gran ventaja, ya que las categorías de documentación aquí pueden dificultar la búsqueda de cosas anteriormente.

5 Me gusta
5

¿Me atrevo a preguntar por una fecha estimada de finalización? Es decir, ¿cuándo se considerará que este plugin es menos experimental y más una versión beta, o quizás incluso una versión candidata a lanzamiento anticipado? Sé lo difícil que es predecir el futuro, así que me contentaré con cualquier estimación aproximada, por muy imprecisa que sea. :wink:

Actualmente estoy explorando Discourse como herramienta en el trabajo, precisamente porque parece capaz de ofrecer una buena combinación de discusiones comunitarias y un espacio compartido para la documentación. Donde es tan fácil escribir documentación como publicar un comentario en un tema.

Por lo tanto, la función de tema wiki por sí sola es genial, por supuesto, es un gran comienzo. Sin embargo, este plugin añade cohesión al contenido de los temas, lo que creo que es esencial para la experiencia del usuario de la documentación.

La categoría de Documentación en meta.discourse.org ahora se siente como un sitio de documentación estructurado adecuado, en lugar de solo algunos temas aleatorios del foro que comparten una categoría y describen cómo funciona Discourse.

Así que, seguid con el buen trabajo. ¡Gracias!

1 me gusta
7

¡Me gusta mucho! La documentación y los discursos encajan muy bien.

¿Tienen planes de habilitar la indexación de etiquetas además de las categorías?

8

Creo que la etapa en la que nos encontramos ahora es “la belleza (o la falta de ella) está en el ojo del espectador”.

Es experimental en el sentido de que hay problemas de UX conocidos, en particular para los responsables del mantenimiento de la documentación y especialmente de los índices, pero es completamente seguro usarlo en producción.

Todo eso quiere decir que agradeceríamos mucho tus comentarios si lo pruebas y lo examinas tú mismo.

No tenemos ninguna ETA en este momento para mejorar los problemas de UX conocidos con el mantenimiento de índices, pero los comentarios de las personas que lo utilizan pueden ayudar a impulsar la dirección allí.

No, esto no es algo que haya surgido en ningún lugar todavía. ¿Puedes compartir un poco más sobre lo que estás pensando o por qué esto sería útil para ti?

4 Me gusta
9

Sobre esto: Si estás en una categoría de documento y cierras una ventana de chat que no está en pantalla completa, la navegación del documento también se “cierra” y la barra de navegación normal vuelve a aparecer. Mientras se reproduce en meta, también noté que al hacer clic en la burbuja de chat (en la esquina superior derecha del encabezado) también se cierra la navegación del documento. ¡Espero que esto ayude!

3 Me gusta
11

Gracias por informarnos. Puedo reproducir el problema, así que lo he registrado y lo incluiremos en el próximo trabajo de desarrollo aquí.

3 Me gusta
13

Eso me recuerda una cosa sobre Discourse como proyecto, que no es realmente ideal para mí como usuario. El hecho de que el proyecto no utilice un rastreador de incidencias público adecuado para errores y planificación.

Por ejemplo, cuando leo la respuesta de Hugh, mi gestor de proyectos interno inmediatamente plantea la pregunta: ¿dónde, dónde se registró esto?. Lo sé, mi gestor interno es una pequeña criatura entrometida, ¿verdad? :slight_smile:

Supongo que usar meta.discourse.org como rastreador de incidencias le da al proyecto la oportunidad de hacer “dogfooding” de Discourse. Y todos los demás rastreadores de incidencias tienen sus propios defectos, por lo que es un fastidio tener que elegir uno. Pero para mí, Discourse, si bien es excelente como foro para preguntas y discusiones, es muy deficiente como rastreador de incidencias. Para ese propósito, carece de categorización efectiva, información sobre versiones afectadas y de destino, números de incidencia, priorización, medios efectivos para filtrar incidencias por estado, antigüedad, prioridad, producto o componentes, y una buena manera de presentar una hoja de ruta para una característica o el producto en su conjunto, entre otras cosas.

Bueno, me desvío. Y todavía no he contribuido con una sola línea de código, informe de error o solicitud de característica, así que, ¿quién soy yo para quejarme? :wink:

Así que, de nuevo, gracias a todos por la genialidad de Discourse. Y perdón por el semi-discurso.

Y volviendo al tema, me alegra saber que las Categorías de Documentación de Discourse, aunque aún no están pulidas, se consideran arquitectónicamente estables. Veré si puedo instalarlo en mi instancia de Discourse alojada y, si es así, intentaré volver con comentarios. ¡Gracias!

6 Me gusta
14

Olvidé responder aquí. Gracias por tu seguimiento.

Entiendo que #wiki podría encajar en diferentes categorías como soporte comunitario dev, y es mejor mostrar datos basados en los intereses de los temas de los usuarios.

Mientras tanto, mostrar esas wikis organizadas en documentos (enlace en la barra lateral de wiki) suena genial.

1 me gusta
15

Usamos Discourse como un rastreador de incidencias. Mejor dicho, intento obligar a mi equipo a usar Discourse como rastreador de incidencias :slight_smile: Y como wiki, y como foro, y como documentación… Sospecho que el equipo de CDCK tiene otro sitio “secreto” de Discourse donde rastrean sus cosas internamente, usando algunos complementos interesantes que nadie tiene…

No importa lo bueno que sea el rastreador de incidencias aquí, la comunidad no se puede comparar con nada más que conozca. Al final, son las personas las que desarrollan el software, no la tecnología detrás de él. ¡Y son geniales! :metal:

Y me gusta mucho el complemento de documentación. :heart:

Ahora, con todos mis elogios, ¿sería posible aprobar mi PR? :smiley:

5 Me gusta
16

¿Viste la respuesta de Gerhard en ese PR?

3 Me gusta
17

Tenemos otro sitio que usamos internamente y es efectivamente cómo rastreamos gran parte de nuestro trabajo. Pero no lo hacemos con ningún complemento secreto.

Principalmente, usamos convenciones, como una categoría para “tareas pendientes” y un conjunto estándar de algunas etiquetas para una especie de priorización ahora/próximo/después, junto con el complemento de asignación para aclarar la propiedad.

Eso también permite que el componente temático kanban funcione, pero no todos usan esa vista.

Es bastante fluido, no es un rastreador de problemas muy dogmático, pero funciona bien para nosotros.

Podría compartir más detalles alguna vez…

6 Me gusta
18

No. Mi culpa. Arreglado. Gracias por el aviso.

3 Me gusta