Diese Seite wurde von der Cloud Translation API übersetzt.

NRNB-Projekt (National Resource for Network Biology)

Auf dieser Seite finden Sie die Details zu einem Projekt für technisches Schreiben, das für Google Season of Docs angenommen wurde.

Projektzusammenfassung

Open-Source-Organisation:: National Resource for Network Biology (NRNB)
Technischer Redakteur:: Prubhtej_9
Projektname:: Nutzerdokumentation für SynBioHub erstellen und Anleitungen für bestimmte Anwendungsfälle entwickeln
Projektdauer:: Standardlänge (3 Monate)

Projektbeschreibung

Zusammenfassung

Eine Nutzerdokumentation soll Endnutzer bei der Verwendung eines Produkts oder einer Dienstleistung unterstützen. Eine gute Nutzerdokumentation ist sehr wichtig, da sie Nutzern die Möglichkeit bietet, die Verwendung einer Software, ihre Funktionen, Tipps und Tricks zu erlernen und auch häufige Probleme bei der Verwendung der Software zu beheben. Außerdem senkt sie die Supportkosten und ist Teil der Corporate Identity des Produkts. Eine gute Nutzerdokumentation ist also ein Zeichen für ein gesundes Produkt und das Entwicklerteam. Ohne eine gute Nutzerdokumentation weiß der Nutzer möglicherweise nicht, wie er die oben genannten Dinge effektiv und effizient erledigen kann. Nutzerdokumentationen können eine entscheidende Rolle für den Erfolg eines Produkts spielen, da eine gute Kommunikation immer im Mittelpunkt eines Unternehmens oder Produkts steht und eine gute Dokumentation diese Kommunikation in ein überschaubares Rahmenwerk stellt, auf das alle für den Erfolg zugreifen können. SynBioHub ist ein Design-Repository für synthetische Biologie. Es ist sowohl als öffentliche Website als auch als Open-Source-Software verfügbar. SynBioHub verwendet Synthetic Biology Open Language (SBOL), einen Open-Source-Standard zur Darstellung von genetischen Designs, und ermöglicht außerdem die Freigabe von Designteilen aus GenBank- und FASTA-Dateien. Mit SynBioHub können Sie eine Bibliothek mit synthetischen Teilen und Designs als Dienst veröffentlichen, Designs mit Mitbearbeitern teilen und Designs biologischer Systeme lokal speichern. Auf Daten in SynBioHub kann über die HTTP API, die Java API oder die Python API zugegriffen werden. Dort können sie dann in CAD-Tools für die Erstellung genetischer Designs eingebunden werden. SynBioHub enthält eine Benutzeroberfläche, über die Nutzer neue biologische Daten in die Datenbank hochladen, DNA-Teile visualisieren, Abfragen ausführen, um auf gewünschte Teile zuzugreifen, und SBOL, GenBank, FASTA usw. herunterladen können. Im Internet sind verschiedene Forschungsartikel und einige Anleitungen verfügbar, z. B.: 1. https://pubs.acs.org/doi/abs/10.1021/acssynbio.7b00403 2. https://pubs.acs.org/doi/abs/10.1021/acssynbio.0c00056 SynBioHub enthält nur eine rudimentäre Dokumentation, die sich nur auf die API bezieht. Für die Benutzeroberfläche gibt es keine Dokumentation.

Aktueller Status der Dokumentation:

Derzeit ist die Nutzerdokumentation unter https://synbiohub.github.io/api-docs/#about-synbiohub verfügbar. Dies ist nur die API-Dokumentation. Es gibt keine GUI-Dokumentation, die dem Nutzer bei der Navigation im Design-Repository helfen kann. Auch die API-Dokumentation muss aktualisiert werden, z. B. um bestimmte spezifische Probleme zu beheben. Die Organisation hat einige Anleitungsvideos aufgenommen, z. B. dieses hier. Es gibt eigentlich keine schriftliche Nutzerdokumentation über SynBioHub, die den Nutzenden als Leitfaden dienen könnte.

Warum ist Ihre vorgeschlagene Nutzerdokumentation eine Verbesserung gegenüber der aktuellen? Ich werde die GUI-Dokumentation von Grund auf neu mit GitHub und Markdown erstellen, wie von meinem Mentor Chris Myers vorgeschlagen. Die vorgeschlagene Nutzerdokumentation wird so strukturiert, dass Effizienz, Konsistenz und Sicherheit für alle Endnutzer verbessert und gewährleistet werden. Es enthält schriftliche Anleitungen und zugehörige Bilder sowie eine Anleitung und Erklärung zur Verwendung der einzelnen Funktionen des Open-Source-Simulators SynBioHub. Während der Gespräche mit Herrn Myers wurde auch entschieden, dass die API-Dokumentation mit der Benutzeroberfläche zusammengeführt wird und sechs Abschnitte enthalten wird, von denen der sechste optional ist. Die Abschnitte werden wie folgt erwähnt: 1. Einführung 2 Installationsanleitung a) Über vorkonfiguriertes Image b) Über Quellcode c) NGINX-Konfiguration 3. Anleitung für Nutzer: a) Detaillierte Anleitungen zur Verwendung der einzelnen Funktionen der Benutzeroberfläche b) Anleitungen für gängige Anwendungsfälle API-Dokumentation – Abschnitt 5: Endpunkte Plug-in-Dokumentation 6. Fehlerbehebung und zukünftige Verweise

Teil 1:

In diesem Abschnitt erhalten die Nutzer eine ausführliche Einführung und verschiedene Anleitungen zu SynBioHub.

Teil 2:

In diesem Abschnitt werden die verschiedenen Möglichkeiten beschrieben, mit denen Nutzer die Open-Source-Software installieren können: a) Über ein vorkonfiguriertes Image b) Über die Quelle c) NGINX-Konfiguration

Teil 3:

Dies ist der wichtigste Teil der Dokumentation und nimmt den größten Teil der Zeit in Anspruch. Hier werden alle Details im Kontext zur Benutzeroberfläche hinzugefügt. Wie bereits erwähnt, werden in diesem Abschnitt hauptsächlich zwei Aspekte behandelt: detaillierte Anleitungen zur Verwendung der einzelnen GUI-Funktionen und einige Anleitungen für gängige Anwendungsfälle.

Teil 4:

Wie bereits erwähnt, wird Slate verwendet, um die Dokumentation dieses Teils zu generieren. In diesem Abschnitt werden die folgenden Endpunkte aufgeführt: 1. Nutzerendpunkte 2. Suchendpunkte 3. Download-Endpunkte 4. Downloadendpunkte 5. Einreichungsendpunkte 6. Berechtigungsendpunkte 7. Endpunkte bearbeiten 8. Anhängeendpunkte 9. Administrationsendpunkte

Teil 5:

In diesem Abschnitt wird die Plug-in-Dokumentation enthalten sein, die bereits in der alten SynBioHub-Dokumentation enthalten ist. Dieser Abschnitt ist in zwei Bereiche unterteilt: Plug-in-Spezifikation und -Implementierung. Teil 6: [optional] Dieser Abschnitt enthält eine Liste sehr häufig auftretender Fehler sowie Anleitungen zur Fehlerbehebung. Wie in der Unterhaltung mit Herrn Myers vereinbart, kann dieser Abschnitt mit dem Einführungsabschnitt zusammengeführt werden, sofern er nicht zu lang wird. Analyse Herr Myers und ich haben darüber gesprochen, wie wir die vorhandene Dokumentation aktualisieren und eine neue für die Benutzeroberfläche schreiben können. In diesen wenigen Gesprächen haben wir ein grundlegendes Layout für die neue Dokumentation formuliert, das oben erwähnt wurde. Auf Seite 5 unten finden Sie einen geschätzten Zeitplan. Wie besprochen, verwende ich GitHub und Markdown, um die Dokumentation für alle Abschnitte zu erstellen, mit Ausnahme von Teil 4 der Dokumentation, für den Slate verwendet wird. Slate: Mit Slate können Sie ansprechende, intelligente und responsive API-Dokumentationen erstellen. Slate ist ein Ruby-basiertes Tool, mit dem aus einer Reihe von Markdown-Dateien eine ansprechende, dreigeteilte statische API-Dokumentationswebsite generiert wird. Es wurde 2013 vom Entwickler Robert Lord entwickelt, als er 18 Jahre alt war und als Praktikant beim Reisesoftwareunternehmen „Tripit“ arbeitete. Er überzeugte seinen damaligen Chef, ihm zu erlauben, das Projekt als Open-Source-Software zu veröffentlichen. Der Rest ist Geschichte. Es bietet folgende Funktionen: Inspiriert von den API-Dokumenten von Stripe und PayPal. Slate ist responsiv und sieht auf Tablets, Smartphones und sogar in Printmedien gut aus. • Alle Informationen auf einer Seite: Vorbei sind die Zeiten, in denen Nutzer eine Million Seiten durchsuchen mussten, um das Gesuchte zu finden. Slate stellt die gesamte Dokumentation auf einer einzigen Seite dar. Die Verknüpfbarkeit wurde jedoch nicht beeinträchtigt. Wenn Sie scrollen, wird der Hashwert Ihres Browsers auf den nächsten Abschnitt aktualisiert. Das Verknüpfen mit einem bestimmten Punkt in der Dokumentation ist also weiterhin ganz einfach. • Slate ist nur Markdown – Wenn Sie Dokumente mit Slate schreiben, schreiben Sie nur Markdown, was das Bearbeiten und Verstehen von Dokumenten erleichtert. Alles ist in Markdown geschrieben – selbst die Codebeispiele sind nur Markdown-Codeblöcke. • Codebeispiele in mehreren Sprachen schreiben: Wenn Ihre API Bindungen in mehreren Programmiersprachen hat, können Sie ganz einfach Tabs einfügen, um zwischen ihnen zu wechseln. In Ihrem Dokument unterscheiden Sie verschiedene Sprachen, indem Sie oben in jedem Codeblock den Sprachnamen angeben, genau wie bei GitHub Flavored Markdown. • Direkt einsatzbereite Syntaxhervorhebung für über 100 Sprachen, keine Konfiguration erforderlich. • Automatisches, flüssig scrollendes Inhaltsverzeichnis ganz links auf der Seite. Beim Scrollen wird Ihre aktuelle Position im Dokument angezeigt. Außerdem ist es schnell. Wir verwenden Slate bei TripIt, um die Dokumentation für unsere neue API zu erstellen. Unser Inhaltsverzeichnis umfasst über 180 Einträge. Wir haben dafür gesorgt, dass die Leistung auch bei größeren Dokumenten hervorragend bleibt. • Ihre Nutzer können die Dokumentation für Sie aktualisieren: Standardmäßig wird Ihre mit Slate erstellte Dokumentation in einem öffentlichen GitHub-Repository gehostet. Dies bedeutet nicht nur, dass Sie Ihre Dokumente mit GitHub-Seiten kostenlos hosten können, sondern es erleichtert auch anderen Entwicklern, Pull-Anfragen an Ihre Dokumente zu senden, wenn sie Tippfehler oder andere Probleme finden. Wenn Sie GitHub nicht verwenden möchten, können Sie Ihre Dokumente natürlich auch an anderer Stelle hosten. • RTL-Unterstützung: Vollständiges Layout von rechts nach links für RTL-Sprachen wie Arabisch, Persisch (Farsi), Hebräisch usw. Verdict: Slate ist eine der leistungsstärksten Open-Source-Software zum Erstellen von Dokumentationen. Gemäß den Gesprächen mit meinem Mentor Chris Myers werde ich Slate für Teil 4 und für andere Teile GitHub und Markdown verwenden. Eine detailliertere Ansicht der Dokumentation wird in den folgenden Abschnitten erläutert. Struktur der vorgeschlagenen Dokumentation Diese Struktur ist zulässig und wurde bereits von Herrn Myers geändert. Projektziele 1. Strukturieren Sie die Dokumentation neu. 2. Aktualisieren Sie die Dokumentation an die modernen Versionen von SynBioHub an. 3. Entfernen Sie veraltete Informationen. 4. Überarbeiten Sie die Nutzerdokumentation, damit sie leichter verständlich ist. 5. Fügen Sie der Dokumentation einen kurzen Abschnitt mit Voraussetzungen für neue Mitwirkende hinzu, damit sie die grundlegenden biologischen Konzepte und die Benutzeroberfläche von SynBioHub besser verstehen.