Workflow pour transformer le contenu Wiki en manuel système

https://stackoverflow.com/questions/618508

wiki
manuals

03-07-2019
|

Question

Nous sommes en train de déployer un nouveau système logiciel pour un grand nombre d'utilisateurs dans de nombreux endroits (plus de 200 utilisateurs dans 8 pays). Dans le passé, nous avons rédigé un manuel pour les utilisateurs, puis le mettons à jour régulièrement. Cela fonctionne bien, car tous les utilisateurs ont le même manuel et couvrent l'essentiel, mais il y a des problèmes, car il n'est pas mis à jour régulièrement, nous manquons parfois des mises à jour et certains utilisateurs auront d'anciennes copies.

Nous avons parlé d'utiliser un wiki lors des phases de test et de déploiement pour créer une base de connaissances sur le système. Idéalement, nous aimerions alors pouvoir convertir cela en un document électronique que nous pourrons ensuite "joliment" et envoyer comme manuel officiel, tout en laissant les utilisateurs utiliser et mettre à jour le wiki.

Quelqu'un d'autre a-t-il fait quelque chose de similaire? Avez-vous des suggestions concernant les systèmes wiki, les flux de travail, les formats de document, etc.?

La solution

La plupart des wikis prennent en charge l'exportation via PDF, par exemple:

Autres conseils

Vous pouvez écrire quelque chose qui génère LaTeX à partir du wiki et convertit un manuel au format PDF. Avec des packages tels que hyperref , vous pouvez conserver des références croisées sous forme de liens hypertexte.

De plus, vous pouvez intégrer du contenu provenant de plusieurs sources, comme un dictionnaire de données, dans le document LaTeX, qui peut être mélangé et mis en correspondance avec le contenu du wiki. Vous pouvez également configurer l’architecture de manière à pouvoir prendre en charge les références croisées dans les deux sens.

Framemaker pourrait également prendre en charge cette fonctionnalité à l'aide de la méthode fichiers MIF et vous pouvez également utiliser Lout de manière similaire ou convertissez le contenu de votre wiki en docbook, , ce qui vous permettrait d'utiliser l'une des nombreuses options de rendu disponibles pour ce format.

Par ailleurs, les publications suivantes de Stackoverflow traitent de divers systèmes de maintenance de la documentation.

Madcap Flare est un outil de création d'aide et de manuel utilisant HTML pour la source de chaque sujet. Vous pouvez assez facilement faire une importation en masse des pages Wiki. Cela nécessiterait alors un peu de nettoyage, mais vous disposerez ensuite d’un système unique à source unique capable de générer des fichiers CHM, une aide sur le Web, des fichiers PDF, DOC / DOCX, etc.

Comment stockez-vous la source d'aide en ce moment? Est-ce que ce sont des fichiers MS Word, MS help, LaTeX?

Si vous placez vos fichiers sources d'aide sous contrôle de version, vous bénéficierez de tous les avantages d'un wiki sans avoir à migrer vers un nouveau système - les utilisateurs peuvent modifier facilement les fichiers d'aide - ces modifications peuvent être suivies, annulées, etc. . et vous obtenez les manuels prettified comme avant.

J'ai suivi les liens de Node et suis tombé sur des pages mediawiki qui, à mon avis, méritaient d'être signalées.

J'ai donné une réponse précédente qui pourrait être utile pour le " wiki au format PDF " partie - utilisez le code ou les fonctionnalités open source PediaPress. Vous pouvez également obtenir des fichiers ODF, même si leurs fichiers PDF sont déjà assez jolis (mais vous voudrez peut-être le renommer et le remodeler pour votre entreprise, je suppose).

Licencié sous: CC-BY-SA avec attribution

Non affilié à StackOverflow