Qu'est-ce qu'un bon outil pour rédiger un manuel d'utilisation (fichier d'aide), qui s'intègre au contrôle de version [fermé]

Question

Les personnes qui rédigent le manuel d'utilisation ne sont pas nécessairement des programmeurs et ont besoin d'un éditeur visuel. Un problème majeur est le format interne de l'outil de création. il devrait être lisible text / html, il est donc facile de comparer des versions de pages individuelles contrôlées dans le contrôle de version.

Answer 1

Il existe d’autres produits professionnels qui permettent la rédaction de fichiers d’aide et qui prennent en charge l’identité "context ID". ce qui permet une aide contextuelle possible. Aide en ligne et RoboHelp sont ce type de produits.

Answer 2

DocBook

_{(source: docbook.org )}

Answer 3

L’Aide d’Aide HTML de Microsoft peut être utilisée pour créer des fichiers d’aide CHM de qualité professionnelle. Tout ce dont vous avez besoin est un groupe de fichiers HTML. L'outil "compile" tous ces éléments et les regroupe dans un seul fichier d’aide. Les fichiers HTML peuvent être générés à l'aide de Microsoft Word / Frontpage ou même de Dreamweaver. Vous voudrez peut-être considérer que la source contrôle ces fichiers HTML.

Answer 4

Latex . Lyx fournit le WYSIWYM pour l'écriture de fichiers latex.

Answer 5

À mon ancien emploi, ils utilisaient un outil du logiciel madcap appelé flare .

Cela semblait vraiment bien fonctionner.

Answer 6

Subversion, DocBook et Publican constituent une bonne combinaison.

• Version control = Sous-version
• Content Authoring = DocBook
• Publishing = Publican
• WYSIWYG en option = Serna

À l’heure actuelle, il s’agit de l’une des chaînes d’outils utilisées par le plus grand fournisseur mondial de solutions open source, ainsi que de nombreux systèmes d’exploitation basés sur Linux dans le monde des entreprises. La plupart (et presque tous) de la documentation officielle de Red Hat est créée de cette manière. Même chose pour Fedora.

Le principal " pro " voila que ce sont des outils librement disponibles, avec un fort chevauchement sur le marché des rédacteurs techniques. Tout ce qui sera capable d'écrire en XML (mais ne le voudra peut-être pas), et ramasser DocBook revient à ramasser du HTML dans les années 90. Subversion est un outil très courant de contrôle de version, qui, comme DocBook, est relativement facile à mettre en oeuvre et à utiliser. Publican est un excellent outil de publication qui peut utiliser DocBook au format XML et le publier en PDF, HTML, HTML unique, etc. Bien entendu, vos rédacteurs peuvent utiliser un WYSIWYG comme Serna, OS X) personnellement.

Le principal " con " est la perception de la technicité. Vos rédacteurs voudront peut-être utiliser WYSIWYG (et l’auront peut-être) et, selon vos besoins en matière de documentation, ce sera peut-être ce que vous utiliserez. Comme vous le savez sûrement, il existe un marché pour les "rédacteurs techniques". qui se spécialisent dans la correction des styles Microsoft Word (et du balisage), donc les arguments pour séparer "créer" à partir de " édition " reposent sur des cas d’utilisation éprouvés mais distincts pour les organisations qui exigent que la documentation soit conforme aux mêmes normes d’ingénierie / programmation / production à la source.

Certains des conseils extrêmes que vous obtiendrez proviennent de personnes et de sociétés ayant été exposées à la valeur de la documentation XML, en particulier de celles appartenant à DITA, où certaines multinationales ont la réputation d'acquérir des acquisitions influencées par le format et la disponibilité de la connaissance du produit. Il existe également des arguments selon lesquels le verrouillage de votre documentation dans un fichier "collant". ou le format fermé n’aide pas les besoins de maintenance futurs C’est là que les options open source sont prises en charge au niveau de l’entreprise. De plus, évidemment, c'est gratuit.

Answer 7

Vous pouvez utiliser Subversion et MGTEK Help Producer. Help Producer crée des fichiers d'aide à partir de documents Word. TortoiseSVN est livré avec des scripts permettant de comparer différentes révisions de documents Word, directement dans Word (Word dispose d’un outil de comparaison de versions).

Vos utilisateurs vont vouloir un outil de diff visuel qui ressemble à celui dans lequel ils sont en train d’éditer. S'ils ne sont pas tout à fait techniques, DocBook ou Latex ne fonctionnent pas (j'ai essayé de donner à mes utilisateurs les deux, et j'ai même essayé Epic Editor en tant qu'éditeur DocBook, ce qui coûte très cher mais ne fonctionne pas très bien après tout). S'en tenir à quelque chose qu'ils savent (Word) vous évitera de nombreux maux de tête.

J’étais également très réticent à suivre cette voie au début, car je voulais une solution plus "techniquement parfaite", mais j’ai réalisé avec le temps qu’avoir des utilisateurs heureux et productifs était plus important. Je ne fais que dire que je sais d'où vous venez, mais essayez l'itinéraire Word. Cela fonctionne beaucoup mieux en pratique que toutes les solutions «pures» basées sur du texte qui existent. Les utilisateurs normaux n'aiment pas l'édition basée sur les balises.

Answer 8

Si vous utilisez Visual Studio, consultez SandCastle - http://www.codeplex.com / Sandcastle .

Plusieurs outils vous aident également à créer des fichiers de châteaux de sable. Essayez de rechercher "& sand; sandcastle". sur codeplex. SandCastle Help File Builder ( http://www.codeplex.com/SHFB ) est l'un d'entre eux. mais je ne l'ai jamais utilisé, donc je ne sais pas si les utilisateurs non techniques seront satisfaits de cela.

Answer 9

Madcap Flare est le meilleur outil commercial du marché. Écrit par les anciens développeurs de Robodoc

Answer 10

J'ai créé un système de documentation appelé Mandown ( Markdown / Html / Javascript / basé sur un fichier documents relativement liés pour la portabilité) qui passerait facilement sous contrôle de version. La partie éditeur visuel que vous auriez à comprendre séparément - j’utilise parfois HTML-Kit qui a au moins une fonctionnalité de prévisualisation.

Voir Quel est le meilleur moyen de stocker des logiciels documentation?

Voici un autre outil à vérifier: Xilize

Answer 11

Nous utilisons APT . Il s'intègre bien avec le CI (artefact de construction standard) et est plus vivant que pour Word, par exemple. Il est également possible de générer des PDF et d’autres formats au besoin.