Welche Plattformen zum Schreiben von Dokumentation/Hilfe/Handbuch verwenden?

Ich bin an einem Punkt angelangt, an dem es absolut notwendig ist, eine Art Dokumentation über mein Produkt zu haben. Also eine Art Hilfe oder Bedienungsanleitung für Kunden, weil ich die Anzahl der E-Mails reduzieren möchte.

Also suchte ich nach etwas, das mir Folgendes ermöglicht:

  • als PDF exportieren

  • übernimmt die Übersetzungen (möglicherweise indem den Übersetzern eingeschränkter Zugriff gewährt wird?)

  • Implementierung online, auf meiner Webseite/Server, ...

  • (keine Bedingung) integrierbar in WordPress

So etwas wie Manula zum Beispiel. Manula ist nicht kostenlos, was kein Problem ist, aber ziemlich teuer, was ein kleines Problem darstellt. Gibt es etwas Ähnliches und vielleicht etwas, das Sie empfehlen würden?

Was benutzt du?

Könnten Sie bitte die beabsichtigte Qualität der jeweiligen ausgegebenen Dokumentformate irgendwie spezifizieren? Etwas, das auf dem Bildschirm gut lesbar ist (mit internen Links usw.), kann oft irgendwie in PDF konvertiert werden , aber das resultierende Dokument sieht normalerweise so aus, wie es ist, im Grunde eine Webseite, die in Druckpapier gezwungen wird. Umgekehrt wirken übersichtliche und strukturierte PDF-Dokumente oft unhandlich, wenn Inhalt und Struktur direkt in so etwas wie HTML übertragen werden. (Ich denke hier an meine Erfahrungen mit DocBook und einigen anderen Multiformat-Generatoren.)
@ORMapper Danke für den Hinweis. Schade, dass ich darüber nicht wirklich nachgedacht habe. Idealerweise möchte ich etwas, das auf dem Bildschirm gut lesbar und gleichzeitig übersichtlich in einem PDF-Dokument ist. Ich denke, das ist keine Option. Wenn ich mich entscheiden müsste, hätte ich lieber Dinge, die gut lesbar und benutzerfreundlich auf dem Bildschirm sind, auf Kosten eines etwas schwächeren Layouts eines PDF-Dokuments.
Das Schöne an Sphinx ist, dass es möglich ist, mehrere übersichtliche Formate aus einer einzigen Quelle zu haben, da jeder Dokumenttyp generiert und nicht konvertiert wird - @Mawg hat natürlich einen Punkt, daher RTFM, aber Sie können kein RTFM wenn es kein Handbuch gibt.

Antworten (3)

Ich persönlich kann den Sphinx Document Generator wärmstens empfehlen :

  • Kostenlos, Gratis & Open Source
  • Plattformübergreifend
  • Ein Satz von Basisdateien im ReStructuredText- Format, die leicht versionierbar sind.
  • Einfaches Einbinden von Screenshots etc.
  • Ausgabeformate: HTML (einschließlich Windows-HTML-Hilfe), LaTeX (für druckbare PDF- Versionen), ePub, Texinfo, Handbuchseiten, einfacher Text.
  • Mechanismen zur Internationalisierung , bei denen die Textwörter und -sätze übersetzt werden und nicht das gesamte Dokument.
  • Mehrere Stile
  • Automatische Generierung von Inhaltsverzeichnis, Index, Querverweisen, Glossar, Zitaten etc.
  • Mehrsprachige und erweiterbare Syntaxhervorhebung
  • Wird von Hunderten von Projekten verwendet, also große Benutzerbasis und viel Unterstützung.

Hinweise zur Internationalisierung

Um die Internationalisierung zu erweitern, die oft I18N genannt wird, weil sie viel weniger zu tippen ist, verwendet Sphinx die gleichen bewährten und bewährten Methoden, die die meisten Open-Source-Projekte seit der Veröffentlichung von gettext im Jahr 1995 verwendet haben .

Sie verwenden ein Message Catalog Builder- Tool innerhalb von Sphinx, um eine Reihe von Dateien zu erstellen , bei denen es sich um Nachrichtenkataloge handelt, streng portierbare Objektvorlagenpot , die Wörter , Sätze und Absätze aus Ihrem Originaldokument enthalten. Kopien davon gehen an den / die Übersetzer für die gewünschte(n) Sprache(n), die ein Tool wie Pootle oder poedit verwenden, um ihre individuellen Übersetzungen bereitzustellen, und sie als tragbare Objektdateien.po zurücksenden . Beachten Sie, dass dies alles gemeinsam mit Diensten wie Transfex erfolgen kann .

Diese .poDateien werden durch das Tool gettext msgfmt ausgeführt, um Nachrichtenobjekte, .moDateien, zu erzeugen. Sobald diese Ihrem Projekt an einer sprachspezifischen Stelle hinzugefügt wurden , können Sie Sphinx erneut ausführen und die Ausgabesprache angeben, und Ihre Dokumente werden in der gewünschten Sprache ausgegeben. Fehlende Übersetzungen bleiben im Originaltext erhalten.

Einer der großen Vorteile dieses Ansatzes besteht darin, dass die Toolkette den Übersetzern anzeigt, was bereits übersetzt ist, wenn Sie Änderungen an Ihren Dokumenten vornehmen, was unvermeidlich ist, und sie müssen nur die neuen/geänderten Elemente und alle fehlerhaften Elemente aktualisieren . Ein weiterer Grund ist, dass Sie niemals mehrere Kopien Ihres Ausgangsdokuments (normalerweise eine pro Sprache) aufbewahren müssen, sondern nur Ihre Übersetzungsdateien.

Sphinx-Übersetzungsworkflow

Workflow mit freundlicher Genehmigung der Sphinx-Website , Strichmännchen ursprünglich aus dem XKCD-Comic

Diagramme & Diagramme

Wenn Ihre Dokumentation Diagramme mit Text enthält, können Sie eine von mehreren Sphinx-Erweiterungen verwenden , z. B. die Graphviz-Erweiterungen, um die Diagramme automatisch zu generieren, im Fall von Graphviz mit der Punktsprache , oder Sie können Diagramme und Diagramme generieren, indem Sie Python einbetten in Ihrem Dokument, wodurch Ihre Diagramme und Diagramme zum Zeitpunkt der Erstellung Ihres Dokuments automatisch aktualisiert werden, Sie können auf diese Weise sogar Text auf Bildern und Fotos überlagern. Das Schöne daran ist, dass Sie Text einbetten, der das Diagramm usw. erstellt, anstatt ihn direkt einzubetten, was sowohl für die Versionskontrolle als auch für die Internationalisierung besser ist. Es gibt auch Erweiterungen für Google Charts & Maps

Weißt du zufällig etwas über die GUI von Sphinx? Meine Frage ist: Wenn ich die Übersetzer in Admin-Seiten lasse: Wissen sie, was zu tun ist, oder brauchen sie zumindest Grundlagen in der Programmierung? Hast du da irgendwelche Erfahrungen?
@skrat Sie müssen den Übersetzern überhaupt keinen Änderungszugriff gewähren und sie benötigen keine Programmiererfahrung. Ich habe meine Antwort erweitert, um mein Verständnis des Prozesses zu vermitteln.
@skrat Sie können auch die gleichen grundlegenden Tools und den gleichen Workflow in Ihrem Code verwenden, um Ihre Software zu internationalisieren. Sie markieren im Grunde Zeichenfolgen an Ort und Stelle, sie werden in die Pot-Datei extrahiert usw., aber die Tags sind auch Makros für zu übersetzende Aufrufe, die ausgewählt werden die Übersetzungen aus der .mo-Datei für die aktuelle Sprache, falls vorhanden. Dies ermöglicht Ihnen sogar, sobald Ihre erste Übersetzung funktioniert, Sprachen hinzuzufügen, ohne Ihren Code neu zu erstellen. Siehe gnu.org/software/gettext/manual/html_node/… für Sprachen.

Mit dem „Writer“ von Libre Offfice können Sie sowohl HTML als auch PDF generieren.

Wenn es soweit ist, können Sie Ihre Dokumente über die HTML-Exportfunktion von Writer ganz einfach für das Web vorbereiten oder automatisch im MediaWiki-Format in einem Wiki veröffentlichen.

Wenn Sie sicher sein müssen, dass das, was Sie veröffentlichen, auf allen Lesegeräten und Plattformen sichtbar ist und genau aussieht, generiert die Funktion "Als PDF exportieren" (.pdf) eine .pdf-Datei. Die PDF-Exportfunktion von LibreOffice bietet eine große Anzahl von Formatierungs- und Sicherheitsoptionen, mit denen Sie auf viele verschiedene Einschränkungen eingehen können, einschließlich der Produktion von ISO-Standard-PDF/A-Dateien.

Ok, aber wie würdest du die Dokumentation/Hilfe mit libre mehrsprachig machen?

In letzter Zeit habe ich gesehen, dass Read the Docs in vielen (OS-)Projekten verwendet wird. Soweit ich das beurteilen kann, zielt es hauptsächlich auf die Codedokumentation ab, ich bin mir nicht sicher, ob das Ihren Anforderungen entspricht.

Lesen Sie die Docs-Hosts-Dokumentation, damit sie vollständig durchsuchbar und leicht zu finden ist. Sie können Ihre Dokumente mit jedem gängigen Versionskontrollsystem importieren, einschließlich Mercurial, Git, Subversion und Bazaar. Wir unterstützen Webhooks, sodass Ihre Dokumente erstellt werden, wenn Sie Code übertragen. Es gibt auch Unterstützung für die Versionierung, sodass Sie Dokumente aus Tags und Zweigen Ihres Codes in Ihrem Repository erstellen können.

Read the Docs verwendet Sphinx als Haupt-Backend und empfiehlt reStructuredText als Übermittlungsformat. Siehe read-the-docs.readthedocs.io/en/latest/getting_started.html
Welche Plattformen zum Schreiben von Dokumentation/Hilfe/Handbuch verwenden?
AntwortenHierDatenschutz-Bestimmungen1y, 0v