Resumen: estoy buscando una manera para que los revisores comenten en colaboración lo más cerca posible de "en línea" en un gran proyecto HTML.
Trabajo en un equipo que documenta un producto grande. El conjunto de documentación HTML tiene cientos de páginas individuales (con una tabla de contenido jerárquica en la barra lateral, como era de esperar); un PDF de todo el conjunto de documentos tiene más de 5000 páginas.
Cuando documentamos una nueva función o realizamos mejoras amplias, como reorganizaciones, publicamos una compilación HTML para que la revisen los desarrolladores, el control de calidad, el soporte, el gerente de producto y otros escritores. Publicamos todo el conjunto de documentos en esta compilación, no solo las páginas modificadas, porque a veces el contexto es importante. Para mitigar eso, proporcionamos enlaces a los temas específicos que cambiaron. De hecho, agregamos estos enlaces al plan de documentos, una especificación que producimos anteriormente que describe los cambios previstos; de esta manera, las personas pueden, si lo desean, ver el trasfondo de por qué hicimos un cambio en particular. El plan doc es una página en el wiki interno.
En este momento, cuando enviamos una solicitud de revisión, dirigimos a las personas a esa página wiki y les pedimos que publiquen sus comentarios como comentarios. Esto permite que todos vean los comentarios de los demás, lo que significa (a) menos repeticiones en comparación con las respuestas individuales y (b) descubrimiento más temprano de los desacuerdos entre los revisores. Pero las largas cadenas de comentarios también pueden ser difíciles de navegar, incluso con subprocesos. Y la gente todavía tiene que hacer un trabajo extra para escribir esos comentarios, porque tienen que decirnos a qué están reaccionando. Los comentarios típicos comienzan con algo como "en 'Instalación de complementos', la descripción en el tercer párrafo no es del todo correcta porque...".
Este enfoque funciona mejor para nosotros que las respuestas por correo electrónico o los comentarios individuales en archivos PDF de solo los temas seleccionados. (Hemos hecho ambas cosas). ¿Hay alguna manera de hacerlo aún más fácil al permitir que las personas adjunten comentarios allí mismo en el HTML, algo así como comentar en Google Docs, pero sin tener que importar nuestro gran conjunto de documentos a algún otra herramienta sólo para este propósito? ¿O es el enfoque actual lo mejor que podemos hacer sin mucho trabajo extra?
Queremos facilitar que las personas comenten y vean los comentarios de los demás. El listón a superar son los comentarios en una página wiki. No estamos interesados en importar un gran conjunto de documentos HTML en alguna otra herramienta (que la gente tendría que aprender). Me pregunto si ya existe, digamos, algún paquete de Javascript que podamos inyectar en estas compilaciones para respaldar este objetivo, o alguna otra forma de lograr este objetivo.
Usamos el control de código fuente (git), y el trabajo de características se realiza en las ramas. Las compilaciones de revisión se producen a partir de esas ramas y son persistentes. (La mayoría de nuestros revisores no se sienten cómodos revisando la fuente HTML, o eludiría todo esto haciendo que revisen la fuente sin procesar en la sucursal).
Usamos Madcap Flare para crear y compilar los documentos. El esquema de Flare para la fuente del documento es un HTML extendido; todo el HTML es válido, además agregan algunas etiquetas específicas de herramientas que se usan en el momento de la compilación. La salida es HTML convencional.
Usamos Jenkins para administrar el proceso de compilación. Jenkins actualmente llama a una secuencia de comandos que realiza algunas tareas domésticas e invoca madbuild.exe (el motor de compilación de Flare). Ese script publica el HTML en un servidor interno. En principio, por lo tanto, podríamos modificar el script de compilación para inyectar algo extra en la salida solo para estas compilaciones de rama. Somos dueños del servidor, por lo que podemos agregarle cosas si es necesario (como una forma de almacenar comentarios).
En un proyecto en el que trabajé, hicimos revisiones a través de un servidor de trabajo en progreso, que era una versión HTML del estado actual de los documentos. Creamos un script de compilación modificado para este servidor que incluía lo siguiente:
Esto era de tecnología relativamente baja. No se comentaron en la propia interfaz de documentos. Pero parecía funcionar bien. Los revisores tenían una manera fácil de indicar a qué se aplicaban sus comentarios de revisión. Creo que tendían a revisar con una ventana de editor de texto abierta y hacían comentarios por número de párrafo, luego lo pegaban en el rastreador de errores. Todas estas eran operaciones a las que estaban bien acostumbrados, por lo que no hubo una curva de aprendizaje ni herramientas desconocidas para usar.
El servidor de trabajo en progreso estuvo activo todo el tiempo que se desarrollaron los documentos, con notificaciones de estado apropiadas sobre cada tema. Descubrimos que varias personas en la organización encontraron útil tener esta información disponible durante el desarrollo y ocasionalmente recibimos comentarios fuera del proceso de revisión formal.
No estoy seguro de poder responder adecuadamente a esto, ya que sé poco sobre desarrollo web. Pero intentaré dar algunas ideas.
Usaría JavaScript para comentar en línea y SQL para almacenar los comentarios.
Haga doble clic/seleccione una palabra en el texto. Aparece un cuadro de comentarios. El usuario puede escribir un comentario y hacer clic en "Aceptar". Se crea un comentario (entrada) y la palabra se resalta. [Opcionalmente, puede permitir que las personas elijan el tipo de comentario (por ejemplo, error ortográfico o error conceptual).]
Se crea una entrada en la base de datos: almacena la URL, el párrafo, la(s) palabra(s) marcada(s).
Cada entrada tiene su propia identificación.
Un script escribe un marcador con el ID en la fuente HTML.
JavaScript abre los comentarios almacenados (marcados) y permite agregar una respuesta. Probablemente también debería agregar tiempo y autor. Lo más fácil sería dejar que el autor escriba su propio nombre único. Mejor sería tener cuentas de usuario al hacer las revisiones.
Dependiendo de sus necesidades, puede optar por mostrar todos los comentarios de esa página en el lado derecho de esa página. O puede abrir un comentario haciendo clic en una palabra resaltada.
Espero poder darte algunas ideas. ¡Buena suerte!
Solución simple:
Solución fácil:
Cada línea del código se almacena en una base de datos como:
Line number String
4763 printf("Hello, World!");
En Wiki, se puede hacer clic en la línea de código. Al hacer clic en él, se despliega un formulario de comentarios debajo de la línea.
En la base de datos, los comentarios se almacenan como:
Line number Comment Comment author
4763 lol John
Cuando hay comentarios para una línea, Wiki muestra la cantidad de comentarios detrás del enlace. Se puede hacer clic en este número. Al hacer clic en él, se muestran los comentarios debajo de la línea, al hacer clic nuevamente se ocultan los comentarios.
Implementar todo esto no debería tomar más de una tarde para un programador experimentado.
Usted dice que "[m]a mayoría de nuestros revisores no se sienten cómodos revisando la fuente HTML". ¿Qué revisan entonces? El resto de su pregunta parece decir que sus revisores miran las líneas de código. ¿No es esa "la fuente HTML"? Si no, explique.
henry taylor
usuario
Mónica Celio
Alejandro
Mónica Celio