Mi empresa actualmente mantiene nuestra documentación técnica (Guía del usuario) en Google Docs. Con cada lanzamiento, produzco un PDF que alojamos en nuestro sitio web.
Estas son las características de Google Docs que funcionan bien:
Y lo no tan agradable:
Tengo la tarea de encontrar una nueva "herramienta" que respalde las siguientes necesidades:
Estoy abierto a ideas con respecto a la plataforma, aunque me encantaría algo basado en la nube.
Esto es lo que hacemos para eso. No está basado en la nube, pero está respaldado por control de fuente, como (espero) que su código ya lo esté.
Herramientas y tecnologías involucradas:
fuente de control
DTD de DocBook
su editor favorito para archivos XML (WYSIWYG posible)
XSLTProc (con ant, pero podría hacer make u otra cosa en su lugar)
XEP (generador de PDF)
(en desuso, pero lo mencionaré de todos modos): HTMLHelp Compiler
Escribimos nuestra fuente de documentación contra el DocBook DTD. Este es un estándar de documentación bien establecido, y aunque toda la especificación es grande, probablemente solo necesite unos 20 elementos XML (etiquetas). Todo lo habitual está ahí: divisiones (libro, capítulo, sección, etc.), formato (énfasis, código, etc.), semántica (nombre de clase, nombre de método, comando, elemento gui, etc.), indexación, tabla de contenido, etc.
Junto con la fuente XML de DocBook, hay hojas de estilo que traducen su entrada XML en cualquier resultado que desee. DocBook viene con algunos de estos. Alimentamos la fuente XML y las hojas de estilo a XSLTProc para producir una salida intermedia, formatear objetos (FO). Luego tenemos un paso para transformar eso en PDF (usando XEP), HTML (usando XSLTProc) y (ya no hacemos esta parte) un archivo CHM de documento HTML (usando HTMLHelp Compiler).
Empaquetamos todos esos pasos de generación en un archivo de compilación ant (ant es lo que ya usamos para nuestras compilaciones de software), pero no hay razón para que no pueda hacerlo a través de make o cualquiera que sea la herramienta de compilación que elija.
La fuente XML se registra en el control de fuente y la colaboración se logra de la manera habitual. XML admite la inclusión de archivos, por lo que puede modularizar sus libros como desee. Debido a que los documentos están en nuestro sistema de control de fuente, es fácil bifurcarlos y etiquetarlos, y las compilaciones nocturnas automatizadas incluyen documentación.
Debido a que la fuente es XML, no un formato binario, las diferencias y fusiones funcionan como cabría esperar, y puede usar cualquier editor que desee. Algunos de nuestros empleados usan Abortext Epic (bastante avanzado), algunos usan Oxygen, otros usan NotePad+XML y al menos una persona anticuada (ejem) usa emacs.
Así que puedo estar infiriendo mucho de tu pregunta, pero...
Puede valer la pena ver una suite de colaboración... con una tienda tan pequeña no costará mucho y las herramientas ofrecen almacenamiento y control de versiones en la nube, publicación web, puede editar los documentos desde la herramienta... aprobaciones, compartir , debates, todo tipo de cosas. Ahora estos son... periféricos a cualquier herramienta que realmente cree el documento. Por lo tanto, podría alojar un documento de Word o un PDF en la nube en una de estas herramientas (Word puede administrar todos los elementos que enumeró) No he visto una herramienta que cree y publique documentos (al menos no de manera efectiva...) puede estar integrado y del mismo proveedor, pero generalmente son dos herramientas.
Entonces, supongo que mi sugerencia se reduce a usar la herramienta de creación de documentos que desee y luego usar una herramienta de colaboración para administrar la publicación, las revisiones, el trabajo simultáneo, etc.
Echa un vistazo a algunos de los siguientes.
Esta herramienta es 10/usuario/mes ofrece intercambio de documentos y colaboración.
Huddle es un poco más caro, 20/usuario/mes, pero tiene muchas funciones... puede hacer todo tipo de cosas geniales, incluidas aplicaciones preconstruidas para acceso móvil.
Este es un poco menos robusto pero es gratuito para hasta 20 usuarios.
Espero que esto ayude, si estoy muy lejos del objetivo, házmelo saber, siempre puedo eliminar esta respuesta.
Diría que está buscando una herramienta de creación de ayuda (HAT) basada en la nube, ya sea SaaS o alojada en servidores en las instalaciones de su empresa.
Hemos utilizado WebWorks ePublisher , que da salida a varios tipos de formatos HTML (por ejemplo, salida HTML propia de WebWorks, ayuda HTML, etc.). También ofrece alojamiento en la nube local (CloudDrafts). Su principal fortaleza es la gran cantidad de salidas que ofrece, lo que puede ser excesivo en su caso, pero vale la pena mirarlo de todos modos.
También puede considerar algunas soluciones SaaS como ClickHelp . Algunos proveedores, como MadCap Software, ofrecen sus HAT en combinación con una solución adicional que debe comprar para que esté basada en la nube.
Tengo una lista adicional de SaaS HAT en DocToolHub si está interesado... simplemente seleccione los filtros para "herramientas de creación de ayuda", "SaaS" y "PDF".
Si desea respaldar la documentación de múltiples productos, la reutilización de contenido (de una manera más eficiente que copiar y pegar) se vuelve deseable. Si ese es el caso, una herramienta como Author-it se adapta a sus requisitos: múltiples formatos de salida, incluidos PDF y HTML, formato de libro adecuado (TOC, índice, etc.), estilos altamente personalizables.
Sus funciones de colaboración están estructuradas de manera un poco diferente al modelo de Google Docs: un autor puede trabajar en un fragmento de texto a la vez, pero ese fragmento de texto puede ser pequeño (una sección). El escritor configura un flujo de trabajo de revisión donde otros pueden comentar, pero no cambiar directamente la fuente. Esto evita guerras de edición y estropear contenido minuciosamente escrito por aficionados.
Lo que lo diferencia de las herramientas habituales de colaboración de oficina es la capacidad de reutilizar el contenido de oraciones individuales a capítulos completos. Esto ahorra mucho tiempo si crea documentación para varios productos.
Hemos estado usando Help & Manual durante siete años. Tiene aproximadamente 8 formatos de salida, usa XML como back-end, se integra bien con svn y se traduce fácilmente usando OmegaT. Permite licencias de usuarios concurrentes (tenemos dos).
Jaime
tmcallaghan