Dieser Leitfaden enthält Anweisungen zum Verfassen effektiver „How-to"-Dokumentation für Discourse. Er behandelt wesentliche Elemente wie Struktur und Stil, Zielgruppenbetrachtung sowie Wartung.
Erforderliches Benutzerlevel: Jeder kann neue How-to-Leitfäden verfassen
Das Verfassen effektiver How-to-Dokumentation ist entscheidend, um Benutzern, Moderatoren, Administratoren und Systemadministratoren zu helfen, verschiedene Aufgaben innerhalb von Discourse auszuführen. Dieser Leitfaden hilft Ihnen dabei, klare und wertvolle How-to-Anleitungen für die Community zu erstellen.
Zusammenfassung
In dieser Dokumentation lernen Sie:
- Warum das Schreiben eines How-to wichtig ist
- Welche Informationen enthalten sein sollten
- Richtlinien für Struktur und Stil
- Wo diese Themen veröffentlicht werden können
- Wie sie nach der Veröffentlichung gewartet werden
Warum ein How-to schreiben?
Ist Ihnen schon einmal eine Aufgabe eingefallen, bei der Sie nicht mehr wussten, wie sie ausgeführt wird? Das Verfassen eines How-to-Dokuments ist eine hervorragende Möglichkeit, Prozesse in Discourse zu dokumentieren. Wenn Sie mit einem bestimmten Prozess Schwierigkeiten haben, geht es wahrscheinlich auch anderen so. Die Dokumentation hilft allen.
Erfahren Sie mehr darüber, was ein How-to von anderen Dokumentationsarten wie Tutorials oder Referenzleitfäden unterscheidet, in diesem Leitfaden von Divio.
Das Schreiben oder Überprüfen eines How-to ist eine großartige Möglichkeit, Ihr Wissen über Discourse der Community zur Verfügung zu stellen. Weitere Möglichkeiten zum Beitrag finden Sie im Leitfaden zum Beitrag zu Discourse.
Welche Informationen sollten enthalten sein?
Ein How-to sollte eine Schritt-für-Schritt-Anleitung sein, die den Benutzer zu einem spezifischen Endergebnis führt. Ein How-to mit dem Titel „HTTPS für Discourse einrichten" sollte beispielsweise Anweisungen zum Einrichten von HTTPS enthalten.
Wichtige Punkte, die beim Verfassen einer How-to-Anleitung zu beachten sind:
- Bleiben Sie beim Thema und seien Sie klar
- Vermeiden Sie unnötige Informationen
- Seien Sie prägnant, aber informativ
- Erklären Sie, warum das Erreichen des Endergebnisses vorteilhaft ist
Berücksichtigen Sie Ihre Zielgruppe
Es gibt verschiedene Zielgruppen für Discourse-How-tos, die jeweils eine unterschiedliche Tiefe der Erklärung erfordern. Verwenden Sie die Dokumentationskategorien als Leitfaden dafür, wen Sie mit Ihrem Leitfaden ansprechen sollen:
- Documentation > Using Discourse
- Documentation > Site Management
- Documentation > Integrations
- Documentation > Hosted Customers
- Documentation > Self-Hosting
- Documentation > Migrating to Discourse
- Documentation > Developer Guides
- Documentation > Contributing
Verstehen Sie das technische Kompetenzniveau Ihrer Zielgruppe und passen Sie Ihren Leitfaden entsprechend an. Einige Tipps:
- Vermeiden Sie Schritte, die die Zielgruppe nicht ausführen kann (z. B. haben gehostete Kunden in der Regel keinen Zugriff auf Konsolenbefehle)
- Halten Sie Anweisungen klar und vermeiden Sie hochtechnische Sprache für nicht-technische Benutzer
- Fügen Sie keine Hintergrundinformationen hinzu, die Ihre Zielgruppe bereits kennen sollte
Struktur und Stil
Der Stil-Leitfaden für die Dokumentation enthält alles, was Sie über die Struktur und den Stil von How-to-Leitfäden (und allen anderen Discourse-Dokumentationen) wissen müssen:
Einen Leitfaden veröffentlichen
Veröffentlichen Sie Leitfäden in einer Unterkategorie der übergeordneten Kategorie Documentation und versehen Sie sie mit dem Tag how-to. Alle Leitfäden müssen vom Discourse-Team genehmigt werden, was automatisch über den Moderationsprozess erfolgt. Der Stil-Leitfaden beschreibt jede Kategorie genauer, um Ihnen bei der Entscheidung zu helfen, wo Ihr Leitfaden veröffentlicht werden soll.
Ihren Leitfaden pflegen
Sobald Sie ein How-to veröffentlicht haben, halten Sie es auf dem neuesten Stand. So können Sie dazu beitragen, es zu pflegen:
- Auf Antworten achten — Integrieren Sie Feedback der Community in den Leitfaden.
- Den Leitfaden selbst testen — Gehen Sie den Leitfaden regelmäßig durch, um sicherzustellen, dass er noch korrekt ist.
- Fehlende oder falsche Informationen bearbeiten — Wenn Sie das Vertrauenslevel 2 oder höher erreicht haben, bearbeiten Sie den ersten Beitrag des How-to.
- Themen zur Unterstützung melden — Wenn Sie keine Bearbeitung vornehmen können, melden Sie den Beitrag mit „Sonstiges" und erklären Sie, was benötigt wird.
In den meisten Fällen werden Kommentare zu offiziellen How-to-Leitfäden nach einem Monat gelöscht, um den Fokus auf den Leitfaden selbst zu legen.
Vielen Dank für die Verbesserung der Discourse-Community-Dokumentation! Wenn Sie feststecken, zögern Sie nicht, um Hilfe zu bitten. Der beste Weg, anzufangen, besteht darin, beizutragen und dabei zu lernen.