Need Beratung - eine flexible Dokumentationssystem entwickeln, stark auf die Lokalisierung konzentriert [geschlossen]

Question

Ich habe mit dem Aufbau einer Dokumentationssystem / Plattform geladen.

Hier ist eine kurze Liste der wichtigsten Anforderungen:

• leicht lokalisiert: Dies muss ein Dutzend oder so Sprachen aus dem Tor unterstützen. (Die Fähigkeit, für nicht-technisches Personal hinzufügen / update Übersetzungen wären ein großes Plus, wenn auch nicht 100% erforderlich)

• Flexibilität in Ausgabeformate: Am Nötigste, ich brauche die Unterlagen Ausgang (entweder als Ganzes oder in ausgewählten Stücken) als PDF und HTML. Bonuspunkte für native Formate wie Windows-Hilfedateien.

• Managed und über eine intuitive Benutzeroberfläche (Web, im Idealfall) eingesetzt werden.

Ich frage mich, wenn Sie Leute wissen, dass Systeme gibt, die Unterstützung dieser Art der Sache schon? Ich bin nicht abgeneigt, das von Grund auf neu zu schreiben, aber ich möchte lieber nicht das Rad neu erfinden, wenn ich ihm helfen kann.

Die beiden wichtigsten Kandidaten, die ich bin gekommen, über so weit DocBook und reST . Die ehemalige scheint einen guten Ruf für sammelte zu haben, na ja, zu saugen. Ich bin mit entweder nicht vertraut, aber ich habe gehört, dass reST würde mir einen guten Teil des Weges dorthin gelangen.

Alle anderen Vorschläge? Würde ich besser dran, das Gebäude von Grund auf neu?

Answer 1

Ich kann DocBook empfehlen, wenn Sie traditionelle technische Dokumentation erstellen müssen: Bücher, in Kapitel unterteilt, in Abschnitte unterteilt, etc. Ich denke, es gibt drei wichtigsten Dinge zu berücksichtigen: das Markup selbst, die Bearbeitung Toolchain und die Veröffentlichung von Toolchain .

Markup. Der DocBook XML-Markup ist sehr umfangreich, Unterstützung für nahezu jeden erdenklichen Aspekt enthielt, was in einem techical Volumen aufgenommen werden könnte und dann einige. Dazu gehört auch die grundlegenden Dinge für Bücher wie Querverweise, Fußnoten, etc. sowie Markup speziell für Software-Dokumentation, wie Programmlisten, Referenzeinträge usw. Der wesentliche Verweis auf das Markup DocBook: The Definitive Guide von Norman Walsh und Leonard Müllner

.

Die Sprache des Inhalts explizit markiert werden kann lang Attribute verwenden, so dass das Quelldokument die Inhalte in mehreren Sprachen enthalten kann und die gewünschte Sprachversion kann in der Verarbeitungsstufe extrahiert werden.

Authoring-Tools. Aufgrund der schieren Größe des DocBook Vokabular, eine Art "Schema-aware" Editor ist so ziemlich eine Voraussetzung. Ein guter Editor werden Ihnen bei der Auswahl der Markup-Elemente helfen und sicherstellen, dass Sie gültigen Markup produzieren. Ein anständiges XML-Editor tun wird, aber je nachdem, wie technische Dokumentation Autoren sind, möchten Sie vielleicht auch etwas benutzerfreundlicher betrachten. Es gibt einige WYSIWYG-Stil Editoren zur Verfügung. (Ich habe verwendet XMLmind XML Editor , und ich war ziemlich zufrieden.)

Publishing-Tools. Die de-facto-Standard Art und Weise Ausgabe von DocBook XML-Markup zu erzeugen, ist die DocBook XSL Sheet Verteilung. Es hat Unterstützung für multple Ausgabeformate wie HTML, XSL-FO (für PDF-Ausgabe), HTML-Hilfe, auch Manpages. Die Ausgabe vom Stylesheet erzeugt wird, kann durch viele Parameter gesteuert werden, und das erste, was zu konsultieren, wenn Sie stimmen wollen die Ausgabe der Referenzdokumentation mit den Sheets verteilt.

Falls und wenn Sie mehr Kontrolle über den erzeugten Ausgang wollen, jedoch müssen Sie das XSLT-Stylesheets für Ihre Anwendung anpassen. Dies mag ein wenig entmutigend, besonders wenn Sie nicht vorherige Erfahrung von XSLT verfügen. Allerdings gibt es ein ausgezeichnetes freies Buch über das Thema zur Verfügung: DocBook XSL: The Complete Guide von Bob Stayton.

Für XSL-FO in PDF konvertieren, werden Sie auch eine XSL-FO-Prozessor benötigen. Es ist die freie und Open-Source- Apahce FOP und dann gibt es mehrere kommerzielle Optionen.

Die meisten wahrscheinlich, Ihr Publishing-Prozess wird wahrscheinlich wie ein Build-System für Ihre Dokumentation am Ende aussehen. Sie werden ein automatisiertes System haben (wahrscheinlich von einem Build-Tool wie Make oder Ant angetrieben), die Dokumentation Quelle in XML nehmen und es in die gewünschten Ausgabeformate in den gewünschten Sprachen schalten.

---

Zusammenfassend möchte ich sagen, dass DocBook ist eine gute Wahl, wenn Sie lineare buchartige, ausführliche technische Dokumentation zu produzieren suchen. Die wichtigsten Nachteile sind die Komplexität des Markup, was eine erhebliche Lernkurve für Autoren präsentieren kann und die speziellen Authoring-Tools erforderlich machen kann. Außerdem kann die Ausgabe von dem DocBook XSL Stylesheets der Anpassung erhält ganz beteiligt.

Wenn Sie weniger zu produzieren suchen „Buch-like“ und „Online-like“ Dokumentation - Dokumentation Themen miteinander verzahnt - möchten Sie vielleicht einen Blick habenunter DITA für eine andere XML-basierte Alternative. Ich habe es nicht benutzt, aber es kommt auch mit einem Werkzeugkette für verschiedene Ausgabeformate aus dem XML-Markup zu erzeugen.

Answer 2

DocBook und ReStructuredText sind auf jeden Fall die beiden größten Konkurrenten, aber asciidoc ist ein weiterer, ähnlich Auszeichnungssprache, die lesbar, unabhängig von der Markup ist. Ich bin mehr vertraut mit (und damit einem größeren Befürworter) ReStructuredText, persönlich, aber asciidoc ist nur eine andere Möglichkeit gibt.

Nach dem, was Sie bisher beschrieben habe, klingt es wie Moinmoin wäre eine gute Passform auf der Grundlage, dass es hat ein ReStructuredText Parser und kann es Seiten in PDF exportieren. Sie sollten die Quelle extrahieren können, und durch was auch immer andere Standalone-Tools wie nötig laufen (aber Sie könnten sie vorverarbeiten müssen jede moin moin spezifische Markup abzustreifen out).

Google hat ein paar andere Ergebnisse für ReStructuredText Wiki wenn Moinmoin isn‘ t genau das, was Sie brauchen.