Welches Werkzeug/Framework für die technische Dokumentation?

Question

Wir entwickeln Produkte und Frameworks für den Einsatz in unserer Organisation. Ich suche Programmierer-freundliche Dokumentationswerkzeuge. Ich habe einige Optionen zu einem späteren Zeitpunkt recherchiert, konnte mich aber nicht entscheiden, welche zu verwenden. Ich bin auf der Suche nach Vorschlägen von Leuten, die diese Werkzeuge bereits benutzt haben.

1. docbook: spring und überwintern Verwendung dieses Format und das sieht gut aus. aber ich glaube, sie haben das Standard-XSLT/Stylesheet angepasst. Kann ich ihre xslt und css (natürlich mit geänderten Farben und Bildern) kopieren und benutzen? Kann ich die doc-Generierung mit maven integrieren?

2. Wiki: Dies ist nicht zu den technischen Dokumentverfasser freundlich und die Dokumentation sieht nicht professionell aus. Versionierung ist auch nicht möglich Ich glaube

3. Word Docs: das ist, was wir derzeit verwenden, aber es ist schwer zu verknüpfen und wiederverwenden gemeinsame Dokumente.

4. DITA?

Answer 1

DocBook

Copy Sheets: ja, können Sie Formatvorlagen kopieren und anpassen. XSL Stylesheets für DocBook sind sehr flexibel, aber nicht einfach zu verstehen. Sie müssen einige Tage einplanen, damit sie so arbeiten, wie Sie es möchten.

Maven Integration: ja, es gibt Maven Plugins, wo Sie die Generation von Dokumenten (z. B. PDF, HTML usw.) in Ihren Build-Prozess integrieren können. Wir tun das, einschließlich Wasserzeichen nur für SNAPSHOTS und Bereitstellung auf Archiva bei der Veröffentlichung.

Answer 2

Nicht sicher, ob Sie sich für zusätzliche Anregungen oder einfach nur Feedback über die, die suchen aufgeführt Sie/haben sie verengt, aber ...

Python eine Kombination aus reStructuredText verwendet und Sphinx, die ist eine Toolchain, die ich bei der Arbeit übernommen habe und genieße.

Von denen, die Sie aufgelistet haben, habe ich Wiki's schon verwendet und es war aus vielen Gründen unangenehm, von denen Sie einige berührt haben. Das Wort scheint auch eine schlechte Wahl zu sein; aus diesen würde ich Docbook wählen, aber ich weiß sehr wenig darüber, also ...

Answer 3

Ich bin ziemlich zufrieden mit DocBook, obwohl die anfängliche Ramp-up (einschließlich Anpassung der Stylesheets) ist nicht so einfach. Aber sobald alles fertig ist, ist es wirklich einfach zu bedienen.

Ich führe meine Docbook-Generation von einer Ant build.xml über die Standard-XSLT-Task. Wenn Sie mit Maven einen XSLT-Prozessor aufrufen können, sollte alles in Ordnung sein.

Der einzige Nachteil (I found) ist die Art und Weise, wie große Bücher verwaltet werden müssen (um zu vermeiden, alles in einer einzigen großer XML-Datei mit)

Jedes Kapitel ist eine separate XML-Datei, die leider ist keine vollständige DocBook-Datei, wie es wird unter Verwendung durch Systemeinheiten enthalten:

 
<?xml version="1.0" encoding="UTF-8"?> 
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 
        "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" 
[ 
    <!ENTITY chapter_1 SYSTEM "chapter_1.xml"> 
    <!ENTITY chapter_1 SYSTEM "chapter_1.xml"> 
]> 

<?xml-stylesheet href="html.css" type="text/css"?> 

<article lang="en"> 
    <title>The Manual</title> 

    &chapter_1; 
    &chapter_2; 

</article> 

Dann sieht chapter_1.xml wie folgt aus:

 
<section id="chapter_1"> 
.... 
</> 

es könnte Wette ter Lösungen da draußen, aber ich habe sie nicht gefunden;)

Answer 4

Die gleiche Frage ist auch in unserem Projekt aufgetreten. Bis zu diesem Zeitpunkt verwendeten wir einfache HTML- und Word-Dokumente, aber diese Lösungen waren nicht befriedigend.

Jetzt verwenden wir DITA und ich empfehle es wirklich. Es ist leichter als DocBook und eignet sich sehr gut für Software-Dokumentation.

Einige Profis:

• DITA Trennung von Inhalt ermöglicht und
• Die Trennung von Inhalt und Styling Styling ermöglicht die Dokumentation für verschiedene Formate, wie HTML oder PDF zu erzeugen. Zum Beispiel erzeugen wir mit DITA die EclipseHelp unserer Eclipse RCP-basierten Anwendung.
• DITA definiert eine Software bestimmten Namespace (z <input> oder <menu-item> und dergleichen)
• DITA mit Build-Skripte für verschiedene Ausgabeformate geliefert wird, die sich leicht an Ihre spezifischen Bedürfnisse angepasst werden kann.

Siehe auch DITA Open Toolkit Project Home

Answer 5

Verwenden Sie ein Wiki.

Ihre Einwände:

ist dies auf die technischen Dokument Autoren nicht freundlich und die Dokumentation professionelle sieht nicht so aus. Versionierung ist auch nicht möglich Ich glaube

Es gibt Wikis, die WYSIWYG-Bearbeitung erlauben. Technische Dokumentation für ein hausinternes Projekt muss nicht "professionell aussehen". Globale Versionierung ist ein Problem, aber ich sehe es nicht als so wichtig an.

Auf der anderen Seite ist der gewaltige Vorteil eines Wikis, der nicht hoch genug eingeschätzt werden kann, besonders für ein internes Produkt: einfach von Beitrag und Zusammenarbeit. Jeder Benutzer des Produkts kann zur Dokumentation beitragen, und wenn Sie eine Kultur der Zusammenarbeit in der Dokumentation etablieren können, ist das Ergebnis (wörtlich) zehnmal nützlicher als der Durchschnitt "Button X tut A, Button Y tut B" Dokumente, die von Autoren erstellt wurden, die das Produkt nicht tatsächlich verwenden. Niemand braucht diese. Die Leute brauchen Anleitungen, Glossare, FAQs und Workarounds.

Wikis ermöglichen und fördern diese Art von nützlicher Zusammenarbeit. "Professionelle" Authoring-Tools mit Zugriffsbeschränkungen und Genehmigungsprozessen töten es.

Answer 6

Sie können auch Ansätze kombinieren:

• Verwenden Wiki für Authoring, da mehr Menschen als nur die Tech-Autoren beteiligt zu haben. Auf diese Weise z.B. Entwickler oder Supportmitarbeiter können leicht teilnehmen.
• Es gibt Tools, die von Wiki zumindest zu DocBook konvertieren, wie das DocBook Wiki oder der Scroll Wiki Exporter meines Unternehmens (http: // k15t.com /), die aus dem Confluence-Wiki nach DocBook exportiert und die DocBook-Stylesheets zur erweiterten Anpassung integriert (s. mhallers Kommentar oben) inkl. RendernX XEP.

hoffe, das hilft,

-Stefan