Hallo,
ich stehe gerade vor der Aufgabe eine Benutzerdokumentation für meine SW
zu erstellen und überlege wie ich das am besten angehe.
Auf jeden Fall soll die Dokumentation online stehen.
Dazu evtl. noch eine offline Variante als PDF oder App.
Das ist zwar aktuell kein Fokus, aber für die Zukunft möchte ich mir
diese Möglichkeit offen halten.
Dabei möchte ich möglichst wenig Aufwand für Einarbeitung und Wartung
des Systems aufwenden um mich vor allem auf den Inhalt konzentrieren zu
können.
Nach kurzer Recherche sind meine Favoriten aktuell in dieser
Reihenfolge:
* Astro Framework mit Docs Theme, Inhalt als Markdown
* Wordpress mit z.B. BetterDocs AddIn
* Ein Wiki
Wie würdet ihr das machen? Andere Ideen? Hat hier jemand Erfahrungen?
Gruß,
Thomas
Thomas-jhfd schrieb:> Wie würdet ihr das machen?
Mit Word (OpenOffice...) schreiben, in PDF oder HTML automatisiert
verwandeln und ins Hilfedateiformat der App.
Der Vorteil: man hat EINE Datei, nicht ein ganzes Verzeichnis, man
findet darin leichter alles. Man sieht die Schrift und
Absatzformatierung, auch wenn die Seitenformatierung höchstens dem
Druckbild entspricht. Die Bedienung ist jedem in der Firma bekannt. Wenn
man die Sekretärinnen aussen vor lässt, die Einrückungen per Leerzeichen
machen, dann hat man keine aus Unkenntnis zernepften Quellen.
Nachteil: es gibt keinen automatischen Import z.B. von Kommentaren oder
Funktionsheadern aus dem Quelltext, aber übliche Endbenutzerdoku enthält
sowieso nichts aus fem Quelltext, daher halte ich Doxygen etc. auch für
völlig fehl am Platze. Anderer Nachteil: eine Datei pro Sprache. Kann
man auch als Vorteil sehen oder notfalls hintereinander schreiben.
Nützlich ist eine Möglichkeit, Abschnitte auszublenden je nach
'Umgebungsvariablen'. So kann man mehrere Versionen in einem Dokument
halten bei dem der Grossteil identisch ist und die passende generieren.
Geht in Word über Formatierungen, z.B. Schriftfarbe
Man sollte sich an die Norm halten: DIN EN 82079.
Die erste Frage ist immer, wer ist Dein Zielpublikum? Der Benutzer
Deiner Software, das ist klar, aber welches Skillset bringen die mit.
Eine Office-Software musst Du zum Beispiel anders dokumentieren als die
Optionen eines Compilers.
Markdown, ist zum Beispiel gut, wenn Du für andere Techniker schreibst,
die wollen Ihre Dokumentation gerne nahe beim Code haben, unter Linux
zum Beispiel, erwartet diese Zielgruppe das sie „man Programmname“
eingeben und die Dokumentation genau für Ihre Version bekommen. Wenn
Dein Zielpublikum aber nicht so technikaffine sind, wäre ein PDF das
Richtige, am besten mit Bildern und Screenshots.
Online Dokumentation auf Webseiten und Apps haben das Problem, dass der
Benutzer meistens nicht die Dokumentation zu der Software Version, die
er hat, bekommt. Das kann Unzufriedenheit beim Benutzer auslösen, wenn
er Transferleistung bringen muss, weil sich zum Beispiel das Menü leicht
verändert hat und die Option nun woanders ist.
Aber Softwaredokumentation ist eine Wissenschaft für sich, und generell
ist man gut beraten, wenn man das einem technischen Schreiber
überlässt. Denn der ist auf das Thema spezialisiert und hat zudem den
Vorteil, dass er näher an der Sicht des Benutzers ist als der Entwickler
der Software.
Danke für den Hinweis auf die Norm (DIN EN 82079).
An Word / LibreOffice habe ich tatsächlich noch nicht gedacht.
Lässt sich allerdings nicht gut versionieren.
Zielgruppe sind zwar Techniker, aber ich dokumentiere nicht meinen Code,
sondern eine GUI SW. Da sehe ich die Anforderungen für den User nicht
anders, als für jedes andere Nachschlagewerk auch: Gute Navigation über
Struktur, Index, Suche.
Die Dokumentation von Asciidoctor gefällt mir sehr gut:
https://docs.asciidoctor.org/asciidoctor/latest/
* Man kann zwischen Versionen umschalten
* Zwischen Sprachen ist vermutlich auch kein Problem
* Inhaltstruktur links
* Seitenstruktur rechts
* Editieren der Seiten direkt in Github / Gitlab im ADOC Format
* HTML generiert mit https://antora.org/
Sieht sehr ähnlich zur bisher favorisierten Variante mit Astro /
Markdown aus.
Deren Doku ist damit generiert:
https://docs.astro.build/en/getting-started/
Office-Dokumente haben den entscheidenden Nachteil dass sie sich
schlecht versionieren lassen. Außerdem bevorzuge ich es, Inhalt und
Layout/Formatierung getrennt zu halten.
Deswegen bin ich auch wieder weg von Markdown.
Le X. schrieb:> Office-Dokumente haben den entscheidenden Nachteil dass sie sich> schlecht versionieren lassen.
Hm, wieso das?
Man gibt dem Dokument eine initiale Versionsnummer, z.B.: 1.0
Diese steht im Dokument selbst drin. Zum Beispiel auf dem Deckblatt,
und/oder in dem Kapitel was die Übersicht der Änderungen enthält. Das
legt man dann in einem Repository ab. Bei der nächsten Änderung hat man
z.B. die Versionsnummer 1.1, diese steht wiederum im Dokument drin
welches dann auch wieder im Repostitory abgelegt wird...
Ich seh grad nicht genau wo das Problem liegen soll?
Mark B. schrieb:> Ich seh grad nicht genau wo das Problem liegen soll?
Weil Binärdateien (bzw. Archive bei den neueren Formaten) sich weder
vernünftig diffen noch mergen lassen. Das sind Features die halte ich
bei der Arbeit mit einer Versionsverwaltung für wichtig.
Aber klar, natürlich kannst du auch Office-Dokumente in git, svn oder
sonstwo reinklatschen. Das System wird dich davon nicht abhalten.
Dann steht dir halt nur ein reduzierter Funktionsumfang zur Verfügung.
Wenn dir das reicht, go for it.
Thomas-jhfd schrieb:> ich stehe gerade vor der Aufgabe eine Benutzerdokumentation für meine SW> zu erstellen und überlege wie ich das am besten angehe.> Auf jeden Fall soll die Dokumentation online stehen.> Dazu evtl. noch eine offline Variante als PDF oder App.
Ich habe gute Erfahrungen mit LaTeX, aber das ist... sagen wir mal, das
entspricht nicht Deinem Wunsch nach einem überschaubaren Aufwand.
Deswegen würde ich das einfach in Markdown schreiben. Das läßt sich mit
pandoc(1) in allerlei Formate umwandeln, natürlich auch (über LaTeX) in
PDFs und HTML-Code, den man zusätzlich noch mit einem Stylesheet schick
aussehen lassen kann.
Karl Käfer schrieb:> Ich habe gute Erfahrungen mit LaTeX, aber das ist...
Außer die Konfiguration ist Latex wohl kaum schwerer als Html.
Persönlich arbeite ich privat seit Jahren mit Lyx und bin zufrieden.
Von wird würde ich die Dinger lassen, wenn ich könnte.
Thomas-jhfd schrieb:> Le X. schrieb:>> Deswegen bin ich auch wieder weg von Markdown.>> Und wo bist du hin?
Ich habe unsere Urlaubsberichte, meine technischen Notizen u.Ä. ne
zeitlang in Markdown geschrieben.
Aber irgendwie war mir das zu fummelig und zu eingeschränkt.
Jetzt schreib ich sowas in ein Excel-template (das so aufgebaut ist dass
es auch meine Freundin gut und gerne benutzen kann, auch unterwegs auf
Reisen), generiere mir per Pythonskript daraus ein xml und mach dann
eine xslt-Transformation und garniere es mit css.
Zugegeben, das klingt etwas wild aber ich generiere mir so statische
Blogs, Bildergallerien und ein kleines Wiki fürs Heimnetzwerk die ohne
Webserver auskommen.
Für deine Zwecke könnt Markdown schon taugen.
Ich würd aber, wie der Käfer geschrieben hat, dann ein html draus machen
oder irgendwas wo du die Formatierung getrennt ablegen kannst.
Auf Arbeit nervts immer wenn sich jedes Jahr das CI ändert und man dann
Dokumentation aus verschiedenen Epochen in unterschiedlichem Design
rumliegen hat.
LaTeX habe ich für meine Diplomarbeit verwendet.
Dafür war das auch gut. Aber kann man damit auch solche Ergebnisse
erzielen?
https://docs.asciidoctor.org/asciidoctor/latest/https://docs.astro.build/en/getting-started/
@Vn N.
Diese Tools scheinen dasselbe in grün zu sein, alles das selbe Konzept.
Da würde ich einfach auf das verbreitetste setzen.
Vermutlich kann man auch später einigermaßen schnell wechseln, wenn die
Hauptarbeit ohnehin in den md / adoc Dokumenten steckt.
Wilhelm M. schrieb:> Ich benutze schon seit Jahren nur noch>> https://asciidoctor.org/>> Ist alles drin. was Du für Single-Source-Doku brauchst.
Was ich vergessen habe zu erwähnen, ist natürlich auch
asciidoctor-diagramm.
Ich nutze auch viel einen Source-Code-Extractor, um Code-Snippets
einzubauen (etwas flexibler als die tag-Mechanik von asciidoctor.
Videos statt Handbuch.
Als Programmierer lese ich immer noch HTML-Seiten. Aber wenn ich ein
Programm benutze, schaue ich mir die Videos an.
Die heute üblichen Oberflächen sind so so übersichtlich - in der Doku
findet man auch nicht mehr als in den Menus und Masken.
Meist brauche ich eine Doku, wenn ich ein Brett vorm Kopf habe. Die
Erklärung im Text verstehe ich genau so falsch, wie die
Benutzeroberfläche. In einem Video fällt dann der Punkt auf, den ich
falsch verstanden habe. Der erzählt das selbe, aber klickt auf eine ganz
andere Stelle.
Ein Anwender schrieb:> Videos statt Handbuch.
Videos sind super, aber nicht statt Handbuch.
Manchmal muss man einfach was nachschlagen, oder offen daneben liegen
haben.
Kunden erwarten zurecht eine schriftliche Dokumentation. Zum Glück nicht
mehr auf Papier.
Wenn ich ein spezielles Problem habe liefert mir eine Suche schnell die
passende Lösung in schriftlicher Form.
Ein Video schauen dauert mir da auch in doppelter Geschwindigkeit zu
lange.
> Die heute üblichen Oberflächen sind so so übersichtlich - in der Doku> findet man auch nicht mehr als in den Menus und Masken.
Das stimmt so pauschal sicher nicht.
Konsumeranwendungen sollten so intuitiv bedienbar sein, wie du
schreibst.
Aber Spezialanwendungen für Experten können kaum mächtig, effizient und
intuitiv zugleich sein.
Beispiel: Excel -> SVERWEIS
Wie geht das noch mal? Würde ich niemals ein Video zu schauen.
Wenn ich hingegen allgemein Excel Funktionen lernen müsste dann auf
jeden Fall mit Video.
Eine Google Suche dazu liefert mir als ersten Treffer das Handbuch von
MS. Dort ist auch ein passendes Video eingebunden. Beide Welten perfekt
vereint, so muss das heutzutage sein.
Schätze mal das bei einer SW-Doku ziemlich oft versioniert wird. Falls
kommerzielle Soft sollten die Änderungen -aus Haftungsgründen-
dokumentiert werden. Ich denke bei einer SW-Doku ist die
Wartungsfreundlichkeit ein wichtiger Posten. Da kann das erste Erstellen
auch mal etwas länger dauern. Ich benutze gerne Scribus, weil ich gerne
grafische Schmankerl einbaue, allerdings nicht für SW-Doku. Schaue dich
mal bei Mitbewerbern um, wie die das machen. OPEN SOURCE benutzen ist
schon mal gut, so hälst du deine erworbenen Kenntnisse portabel.
Deine oben genannten Tools gehen wahrscheinlich alle drei. Pick dir ein
paar Kriterien raus und versuche zu vergleichen. Wie gesagt, einfache
Versionierung ist wichtig...
Thomas-jhfd schrieb:> Zielgruppe sind zwar Techniker, aber ich dokumentiere nicht meinen Code,> sondern eine GUI SW. Da sehe ich die Anforderungen für den User nicht> anders, als für jedes andere Nachschlagewerk auch
Es gibt verschiedene Arten von Benutzerdokumentationen; nicht jede ist
ein Nachschlagewerk.
Ich empfehle die Lektüre dieser Webseite: https://diataxis.fr/> Diátaxis identifies four modes of documentation - tutorials, how-to> guides, technical reference and explanation.>> Each of these modes (or types) answers to a different user need, fulfils> a different purpose and requires a different approach to its creation.
Die Entscheidung ist nun für Markdown / Astro gefallen.
Asciidoctor / Antora war auch noch im Rennen und wäre sicher mindestens
ebenso gut geeignet gewesen.
Alle anderen Optionen waren eigentlich sehr schnell raus.
Ersteres ist es vor allem deshalb geworden, weil ich es zuerst evaluiert
habe, mich schnell damit angefreundet habe und es alle meine Erwartungen
erfüllt.
Der Einstieg war noch leichter als gedacht, bereits nach wenigen Stunden
stand die Struktur. Von der Evaluierung ging es fließend in die
Umsetzungsphase. Warum dann noch Zeit in eine weitere Evaluierung
stecken.
Einen wesentlichen Anteil am Entscheidungsprozess hatte dieses tolle
Video:
https://www.youtube.com/watch?v=uyIsNm25W3M
Zwar ohne Markdown, aber dafür gibt es gute Beispiele im von mir
verwendeten Docs Theme:
https://github.com/withastro/astro/tree/main/examples/docs
Astro hat den Fokus nicht auf Dokumentation, sondern allgemein auf das
Generieren statischer Websites.
Antora hingegen fokussiert voll auf das Generieren von Dokumentation aus
Git Repositories.
Dabei können Repositories für Produkte, und Branches für Versionen
angelegt werden.
Das ist sehr mächtig und wegen der Version-Unsterstützung für z.B. API
Referenzen vermutlich deutlich besser geeignet als Astro.
Ein gutes Video dazu gibt es hier:
https://www.youtube.com/watch?v=BAJ8F7yQz64
Ich hoffe ich habe das einigermaßen korrekt und vollständig
zusammengefasst.
