Umfassendes technisches Dokumentationstool

Hintergrund

Sie möchten die technische Dokumentation vereinheitlichen, indem Sie computer- und benutzergenerierte Inhalte mithilfe von Open-Source-Tools verbinden. Das Ziel besteht darin, Inhalte in einem Ausgabe-agnostischen Dateiformat zu schreiben (oder zu generieren), das dann in ein endgültiges Dokument umgewandelt wird. Die folgende Abbildung hilft zu veranschaulichen, wie sich die Gesamtteile verbinden.

Dokumentationsarchitektur

Die Lösung sollte betriebssystemunabhängig sein.

Ausgabefunktionen

Das Abschlussdokument muss enthalten:

  • Tische
  • Zahlen
  • Code Ausschnitte
  • Automatisch nummerierte Bildunterschriften (für Tabellen, Abbildungen und Codeausschnitte)
  • Querverweise (Hyperlinks zu Tabellen, Abbildungen und bibliografischen Zitaten)
  • Überschriften (bis zu sieben Ebenen; 1., 1.1., ..., 1.1.1.1.1.1.1.)
  • Anhänge (bis zu sieben Stufen; A., A.1, ..., A.1.1.1.1.1.1.)
  • Automatisch nummerierte Überschriften und Anhänge
  • Inhaltsverzeichnis (mit Hyperlink)
  • Tabellenverzeichnis (mit Hyperlink)
  • Abbildungsverzeichnis (mit Hyperlink)
  • Bibliografie (Bücher, Artikel, Zeitschriften, Whitepaper, Websites [mit Hyperlink])
    • Vielzahl von Formaten (APA, Chicago, IEEE etc.)

Am wichtigsten ist, dass eine Stilisierung (durch Vorlagen oder Codierung) möglich sein sollte, damit die gesamte Dokumentation mit einem neuen Erscheinungsbild neu erstellt werden kann. ConTeXt zum Beispiel zeichnet sich dadurch aus.

Markdown und Pandoc bieten viele dieser Funktionen, obwohl ich nicht sicher bin, ob Querverweise, automatische Beschriftungen, Bibliographien und Code-Snippets verarbeitet werden.

Eingabefunktionen

  • Dokumentübergreifende Variablen (z. B. ein Servername wird einmal dokumentiert, aber von Anwendungsarchitektur und Softwareanforderungsspezifikationen referenziert).
  • Browserbasierter WYSIWYG-Editor (evtl. Confluence)
    • Tabelleneditor
    • Transklusion (eingebettete Auszüge zur Unterstützung von Single-Source-Inhalten)
    • Kollaborativ (idealerweise in Echtzeit)
    • Revisionen
    • Markdown (Möglichkeit, den Quelltext anzuzeigen, wird aber überwiegend wie ein modernes Textverarbeitungsprogramm verwendet)
  • Computergenerierte Inhalte werden in das Markdown-Format umgewandelt:
    • Quellcode-Dokumentation (Paketbeschreibungen, kein verlinkter Inhalt erforderlich); Javadocs, Doxygen usw.
    • SNMP (Namen und IP-Adressen von Netzwerkgeräten)
    • Diagramme (Entity-Relationships, UML, GraphViz, etc.)
      • Idealerweise könnten JPG-, PNG- und SVG-Bilder importiert werden
    • Liste der Datenbank-Ersatzschlüssel und -Beschreibungen (aus der Datenbank ausgegeben)

Fragen

Ist es überhaupt möglich, ein hochwertiges technisches Dokument zu erstellen, das eine so große Vielfalt an Artefakten enthält, indem nur Markdown als Quellinhalt verwendet wird?

Hier sind die Stücke, zu denen ich Empfehlungen oder Vorschläge zu schätzen weiß:

  • Einschließlich Quellcode (z. B. Javadoc/Doxygen -> Markdown)
  • Möglichkeit, verschiedene *nix-Befehlsausgaben in Markdown umzuformatieren ( nmap, traceroute, ls, tree, df, SNMP-Ausgabe usw.); die Übersetzung könnte zum Beispiel mit awkund massiert werden .sed
  • WYSIWYG-Editor (FOSS- Alternativen zu Confluence)
  • FOSS, das die Ausgabefunktionen aus der Markdown-Quelle in die gewünschten Ausgabeformate umwandeln kann (auf jeden Fall PDF und optional MS Word).
    • Wenn Pandoc/ConTeXt dieses Kunststück nicht vollbringen kann, was kann es dann?
  • Software und/oder Datenformate (z. B. Markdown, YAML) zum Einbinden von Literaturverzeichnissen und Querverweisen, damit der Dokumentengenerator (z. B. ConTeXt) diese verwenden kann (z. B. RStudio ) ?

Wenn es ein einziges Softwarepaket gibt, das all diese Funktionen vereint, würde ich das auch gerne wissen.

Verwandt

Verwandte Fragen sind:

Software

Spezifikationen

Antworten (1)

Ich bin ziemlich sicher, dass Sie ein wenig arbeiten werden, wenn Sie etwas sehr Ähnliches wie das, was Sie beschreiben, mit Sphinx Docs einfügen könnten . Der einzige Bereich, in dem Sie möglicherweise Probleme haben, ist die kollaborative Bearbeitung in Echtzeit.

  • Das Basisformat ist restrukturierter Text (anstelle von Markdown), aber Eingaben können in Markdown erfolgen.
  • Mehrere Ausgabeformate
  • Mehrere Eingabequellen, einschließlich Quellcode, Wiki, Online usw.
  • Kann während des Build-Prozesses mehrere Tools aufrufen und nachbearbeiten
  • Plattformübergreifend
  • Open Source
  • Erzeugt eine wirklich gut aussehende Dokumentation
  • Alle gewünschten Ausgabefunktionen verfügbar
  • Vorlagen - Ja
  • Dokumente mit mehreren Ausgabeformaten erstellen – Ja
  • Syntaxhervorhebung von Codefragmenten in mehreren Sprachen dank Pygments.
  • Umfangreiche Querverweise: semantische Auszeichnungen und automatische Links für Funktionen, Klassen, Zitate, Glossarbegriffe und ähnliche Informationen.
  • Gute Internationalisierungsunterstützung mit gettext.
  • Erweiterbar und aktiv weiterentwickelt.
Vielen Dank. Sieht so aus, als gäbe es einen XML-Builder, der mit ConTeXt verwendet werden könnte. sowie etwas, das eine ConTeXt-Builder- Erweiterung zu sein scheint.
In einem Beispiel mit Anhang verwenden die Überschriftennummern keine Buchstaben. Dies könnte jedoch ein Versehen/eine Fehlkonfiguration der zum Rendern des PDF verwendeten Engine gewesen sein.
Ich habe gerade einige Tests basierend auf docutils.sourceforge.net/docs/ref/rst/… durchgeführt und diese funktionieren gut für die automatische Aufzählung – sogar für die römischen Ziffern.
Umfassendes technisches Dokumentationstool
AntwortenHierDatenschutz-Bestimmungen1y, 0v