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.
:
Bearbeitet durch User
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.
Ich benutze schon seit Jahren nur noch https://asciidoctor.org/ Ist alles drin. was Du für Single-Source-Doku brauchst.
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.
Artikel zu Asciidoctor: https://www.heise.de/hintergrund/Documentation-as-Code-mit-Asciidoctor-4642013.html https://www.informatik-aktuell.de/entwicklung/methoden/docs-as-code-die-grundlagen.html
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.
:
Bearbeitet durch User
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.
Wilhelm M. schrieb: > asciidoctor-diagramm Interessant, aber das wäre mir zu umständlich, würde ich mit Visio machen.
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.
Thread beobachten
Seitenaufteilung abschaltenBitte melde dich an um einen Beitrag zu schreiben. Anmeldung ist kostenlos und dauert nur eine Minute.
Bestehender Account
Schon ein Account bei Google/GoogleMail? Keine Anmeldung erforderlich!
Mit Google-Account einloggen
Mit Google-Account einloggen
Noch kein Account? Hier anmelden.