Besoin de conseils - L'élaboration d'un système de documentation souple, fortement axée sur la localisation [fermée]

Question

J'ai été chargé de la construction d'un système de documentation / plate-forme.

Voici une courte liste des principales exigences:

• facilement localisé: Cela devra soutenir une douzaine de langues de la porte. (La possibilité pour le personnel non technique pour ajouter / mettre à jour les traductions serait un gros plus, mais pas 100% requis)

• La flexibilité dans les formats de sortie: Au minimum, je dois sortir les documents (soit dans son ensemble ou en morceaux choisis) comme PDF et HTML. Les points bonus pour les formats natifs comme Windows fichiers d'aide.

• Géré et déployé par l'intermédiaire d'une interface utilisateur intuitive (web, idéalement).

Je me demande si vous connaissez des gens là-bas systèmes supportant ce genre de chose déjà? Je ne suis pas opposé à écrire ce à partir de zéro, mais je préfère ne pas réinventer la roue si je peux l'aider.

Les deux principaux candidats, je suis venu à travers ce jour sont DocBook et reST . Le premier semble avoir acquis une réputation pour, bien, sucer. Je ne suis pas familier avec non plus, mais on me dit que reST me obtiendrait une bonne partie du chemin.

Toutes les autres suggestions? Serais-je mieux construire ce à partir de zéro?

Answer 1

Je peux recommander DocBook si vous avez besoin pour créer la documentation technique traditionnelle: livres, divisés en chapitres, divisés en sections, etc. Je pense qu'il ya trois principales choses à considérer: le balisage lui-même, l'ensemble des outils d'édition, et la chaîne d'outils d'édition .

Markup. Le balisage XML DocBook est très complet, contenant le soutien pour à peu près tous les aspects imaginables ce qui pourrait être inclus dans un volume techical puis certains. Cela inclut les trucs de base pour des livres comme des références croisées, notes, etc., ainsi que le balisage spécifiquement pour la documentation du logiciel, comme des listes de programmes, référence à des entrées etc. La référence essentielle à la balise est DocBook: The Definitive Guide par Norman Walsh et Leonard Muellner

.

La langue du contenu peut être explicitement marqué à l'aide des attributs de lang, de sorte que le document source peut contenir le contenu en plusieurs langues, et la version de langue souhaitée peut être extrait à l'étape de traitement.

outils de création. En raison de la taille du vocabulaire DocBook, une sorte d'éditeur « schéma conscient » est à peu près une exigence. Un bon éditeur vous aidera avec le choix des éléments de balisage et assurez-vous de produire un balisage valide. Un éditeur XML décent va faire, mais selon la façon dont les auteurs techniques votre documentation sont, vous pourriez aussi envisager quelque chose de plus convivial. Il y a quelques éditeurs de style WYSIWYG disponibles. (Je l'ai utilisé XMLmind XML Editor , et j'étais assez content.)

outils de publication. de facto moyen standard de générer une sortie de balisage XML DocBook est le DocBook de la distribution de XSL stylesheet. Il supporte les formats de sortie multple, y compris HTML, XSL-FO (pour la sortie PDF), HTML Help, même les pages de manuel. La sortie générée par la feuille de style peut être contrôlé par de nombreux paramètres, et la première chose à consulter quand vous voulez régler la sortie est le documentation de référence distribués avec les feuilles de style.

Si et quand vous voulez plus de contrôle sur la sortie produit, cependant, vous devez personnaliser les feuilles de style XSLT pour votre utilisation particulière. Cela peut sembler un peu intimidant, surtout si vous n'avez pas d'expérience préalable de XSLT. Cependant, il y a un excellent livre gratuit disponible sur le sujet: DocBook XSL: Le guide complet par Bob Stayton.

Pour la conversion XSL-FO au format PDF, vous aurez également besoin d'un processeur XSL-FO. Il y a la source libre et ouvert Apahce FOP et puis il y a plusieurs options commerciales.

Très probablement, votre processus d'édition finira probablement ressembler à un système de construction pour votre documentation. Vous aurez un système automatisé (probablement tirée par un outil de construction comme Marque ou Ant) qui prendra votre source de documentation en XML et d'en faire les formats de sortie souhaitées dans les langues souhaitées.

---

En résumé, je dirais que DocBook est un bon choix si vous cherchez à produire des livres comme linéaire, une documentation technique détaillée. Les principaux inconvénients sont la complexité du balisage, qui peut présenter une courbe d'apprentissage considérable pour les auteurs, et qui peuvent faire des outils spéciaux de création nécessaires. En outre, la personnalisation de la sortie des feuilles de style DocBook peut XSL devenir assez impliqués.

Si vous cherchez à produire moins « livre-like » et plus « en ligne comme » documentation - sujets de documentation reliés entre eux les uns aux autres - vous voudrez peut-être un coup d'oeil DITA pour une autre alternative XML. Je ne l'ai pas utilisé, mais il est également livré avec un ensemble d'outils pour la production de divers formats de sortie à partir du balisage XML.

Answer 2

DocBook et ReStructuredText sont certainement les deux plus grands concurrents, mais Asciidoc est un autre, similaire langage de balisage lisible quel que soit le balisage. Je suis plus familier avec (et donc un plus grand promoteur de) ReStructuredText, personnellement, mais Asciidoc est juste une autre option là-bas.

Étant donné ce que vous avez décrit jusqu'à présent, il semble que MoinMoin serait un bon ajustement sur la base que il a un analyseur ReStructuredText et il peut exporter des pages au format PDF . Vous devriez être en mesure d'extraire la source et l'exécuter à travers tout autre outils autonomes au besoin (mais vous pourriez avoir besoin de les prétraiter enlever toute balisage spécifique à MoinMoin).

Google a quelques autres résultats pour ReStructuredText wiki si MoinMoin n » t exactement ce dont vous avez besoin.