Diese Seite wurde von der Cloud Translation API übersetzt.

NRNB-Projekt (National Resource for Network Biology)

Diese Seite enthält die Details zu einem Projekt für technisches Schreiben, das für die Google-Produktsaison von Google Docs akzeptiert wurde.

Projektzusammenfassung

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

Projektbeschreibung

Zusammenfassung

Eine Nutzerdokumentation soll Endnutzer bei der Verwendung eines Produkts oder einer Dienstleistung unterstützen. Eine gute Benutzerdokumentation ist sehr wichtig, da sie Nutzenden die Möglichkeit bietet, die Verwendung einer Software zu erlernen, ihre Funktionen, Tipps und Tricks sowie die Lösung häufig auftretender Probleme bei der Verwendung der Software. Es senkt auch die Supportkosten und ist Teil der Corporate Identity des Produkts, d.h. eine gute Nutzerdokumentation ist ein Zeichen für ein fehlerfreies Produkt und das Entwicklerteam. Ohne eine gute Nutzerdokumentation wissen Nutzende möglicherweise nicht, wie sie die oben genannten Aufgaben effektiv und effizient erledigen können. Benutzerdokumentationen können eine entscheidende Rolle für den Erfolg eines Produkts spielen, da gute Kommunikation im Mittelpunkt jedes Unternehmens oder Produkts steht und immer sein wird. Eine gute Dokumentation fügt diese Kommunikation einfach in ein überschaubares Framework ein, auf das jeder Zugriff hat, um erfolgreich zu sein. SynBioHub ist ein Design-Repository für synthetische Biologie. Sie ist sowohl als öffentliche Website als auch als Open-Source-Software verfügbar. SynBioHub nutzt Synthetic Biology Open Language (SBOL), einen Open-Source-Standard zur Darstellung genetischer Designs, und ermöglicht auch die Freigabe von Designteilen aus GenBank- und FASTA-Dateien. Mit SynBioHub können Sie eine Bibliothek mit synthetischen Teilen und Designs als Service veröffentlichen, Designs mit Mitbearbeitern teilen und Designs von biologischen Systemen lokal speichern. Auf Daten in SynBioHub kann über die HTTP API, die Java API oder die Python API zugegriffen werden, wo sie dann in CAD-Tools zur Erstellung genetischer Designs eingebunden werden können. SynBioHub enthält eine Oberfläche, über die Nutzer neue biologische Daten in die Datenbank hochladen, DNA-Teile visualisieren, Abfragen für den Zugriff auf die gewünschten Teile durchführen und SBOL, GenBank, FASTA usw. herunterladen können. Außerdem sind verschiedene Forschungsberichte und Anleitungen im Internet verfügbar, z. B.:

Aktueller Stand der Dokumentation:

Die Nutzerdokumentation ist derzeit unter https://synbiohub.github.io/api-docs/#about-synbiohub verfügbar. Es handelt sich lediglich um die API-Dokumentation und die GUI-Dokumentation, die Nutzern bei der Navigation im Design-Repository hilft. Auch die API-Dokumentation muss etwas aktualisiert werden, um spezifische Themen wie die Behebung bestimmter besonderer Probleme zu berücksichtigen, mit denen Nutzer konfrontiert sein können. Die Organisation hat einige Anleitungsvideos aufgenommen, wie dieses hier. Es gibt wirklich keine schriftliche Nutzerdokumentation zu SynBioHub, die Nutzer anleiten kann.

Warum ist Ihre vorgeschlagene Nutzerdokumentation eine Verbesserung gegenüber der aktuellen? Ich werde die GUI-Dokumentation mithilfe von GitHub und Markdown ganz neu erstellen, wie vom Mentor Chris Myers vorgeschlagen. Die vorgeschlagene Nutzerdokumentation ist so strukturiert, dass sie Effizienz, Einheitlichkeit und ein sicheres Gefühl für alle Endnutzer gewährleistet. Sie enthält schriftliche Leitfäden und die zugehörigen Bilder sowie Anleitungen und Erklärungen zur Verwendung der einzelnen Funktionen des Open-Source-Simulators SynBioHub. Bei den Gesprächen mit Herrn Myers wurde außerdem beschlossen, die API-Dokumentation mit der GUI zusammenzuführen und sechs Abschnitte zu enthalten, von denen der sechste optional ist. Die Abschnitte werden wie folgt erwähnt: 1. Einführung 2. Installationsanleitung a) Aus vordefiniertem Image b) Aus Quelle c) NGINX-Konfiguration 3. Bedienungsanleitung a) Detaillierte Anleitungen zur Verwendung der einzelnen GUI-Funktionen b) Anleitungen für häufige Anwendungsfälle 4. API-Dokumentation – Abschnitt 5 zu Endpunkte Plug-in-Dokumentation 6. Fehlerbehebung und künftige Referenzen

Teil 1:

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

Teil 2:

In diesem Abschnitt werden die verschiedenen Möglichkeiten beschrieben, über die Nutzer die Open-Source-Software mit verschiedenen Methoden installieren können, nämlich: a) Aus einem vordefinierten Image, b) Aus der Quelle c) NGINX-Konfiguration

Teil 3:

Dies ist der wichtigste Teil der Dokumentation und wird die meiste Zeit in Anspruch nehmen. Hier wird jedes Detail der GUI im Kontext hinzugefügt. Wie bereits erwähnt, werden in diesem Abschnitt hauptsächlich zwei Probleme behandelt, d.h. detaillierte Anleitungen zur Verwendung der einzelnen GUI-Funktionen und einige Anleitungen für häufige Anwendungsfälle.

Teil 4:

Wie bereits erwähnt, wird das Slate verwendet, um die Dokumentation für diesen Teil zu generieren. Dieser Abschnitt umfasst die folgenden Endpunkte: 1. Nutzerendpunkte 2. Suchen Sie in Endpoints. 3. Laden Sie Endpoints herunter 4. Laden Sie Endpoints herunter 5. Endpunkte senden 6. Berechtigungsendpunkte. 7. Bearbeiten Sie "Endpunkte". 8. Anhang: Endpunkte 9. Verwaltungsendpunkte

Teil 5:

In diesem Abschnitt finden Sie die Plug-in-Dokumentation, die in der alten SynBioHub-Dokumentation bereits vorhanden ist. Dieser Abschnitt wird in zwei Abschnitte unterteilt: „Plug-in-Spezifikation“ und „Implementierung“. Teil 6: [Optional] In diesem Abschnitt findest du eine Liste mit häufigen Fehlern, die bei Nutzern auftreten, sowie Anleitungen zur Fehlerbehebung. Gemäß der Diskussion mit Mr. Myers wurde beschlossen, dass dieser Abschnitt mit dem Einführungsabschnitt zusammengeführt werden kann, falls dies nicht zu lang wird. Analyse Herr Myers und ich haben uns darüber unterhalten, wie die vorhandene Dokumentation aktualisiert und eine neue für die GUI erstellt werden sollte. In diesen wenigen Gesprächen haben wir ein grundlegendes Layout für die neue Dokumentation (siehe oben) formuliert und unten auf Seite 5 einen geschätzten Zeitrahmen angegeben. Wie in der Diskussion erwähnt, verwende ich GitHub und Markdown zum Erstellen der Dokumentation für jeden Abschnitt mit Ausnahme von Teil 4 der Dokumentation, in der das Slate verwendet wird. Slate: Mit Slate können Sie ansprechende, intelligente und responsive API-Dokumentationen erstellen. Slate ist ein Ruby-basiertes Tool, das aus einer Reihe von Markdown-Dateien eine ansprechende, dreiteilige statische Dokumentationswebsite für die API erstellt. Er wurde 2013 von dem Entwickler Robert Lord als 18-jähriger Praktikum bei dem Reisesoftwareunternehmen Tripit entwickelt. Er überzeugte seinen damaligen Chef, das Projekt als Open Source veröffentlichen zu lassen. Der Rest ist Geschichte. Sie verfügt über die folgenden Funktionen: • Klares, intuitives Design: Bei Slate befindet sich die Beschreibung Ihrer API auf der linken Seite Ihrer Dokumentation und alle Codebeispiele befinden sich auf der rechten Seite. Inspiriert von den API-Dokumenten von Stripe und PayPal Slate ist responsiv und sieht daher auf Tablets, Smartphones und sogar in Printmedien toll aus. • Alles auf einer Seite – Die Zeiten, in denen Nutzer auf unzähligen Seiten suchen mussten, um das Gesuchte zu finden, sind vorbei. Slate stellt die gesamte Dokumentation auf einer einzigen Seite zusammen. Dabei haben wir jedoch nicht auf die Verlinkbarkeit gelegt. Beim Scrollen wird der Hashwert Ihres Browsers in den nächstgelegenen Header geändert, sodass das Verlinken zu einem bestimmten Punkt in der Dokumentation ganz natürlich und einfach ist. • Slate ist nur Markdown: Wenn Sie Dokumente mit Slate schreiben, schreiben Sie einfach Markdown, was das Bearbeiten und Verstehen einfacher macht. 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 einfach in Tabs zwischen ihnen wechseln. In Ihrem Dokument können Sie die verschiedenen Sprachen unterscheiden, indem Sie den Sprachnamen oben in jedem Codeblock angeben, wie bei GitHub Flavored Markdown. • Sofort verfügbare Syntaxhervorhebung für über 100 Sprachen, keine Konfiguration erforderlich. • Automatisches, reibungsloses Scrollen des Inhaltsverzeichnisses ganz links auf der Seite. Beim Scrollen wird Ihre aktuelle Position im Dokument angezeigt. Das geht auch schnell. Wir verwenden Slate bei TripIt, um die Dokumentation für unsere neue API zu erstellen, die unser Inhaltsverzeichnis über 180 Einträge umfasst. Wir haben darauf geachtet, dass die Leistung auch bei größeren Dokumenten hervorragend bleibt. • Lassen Sie Ihre Nutzer die Dokumentation für Sie aktualisieren: Die von Slate generierte Dokumentation wird standardmäßig in einem öffentlichen GitHub-Repository gehostet. Dies bedeutet nicht nur, dass Sie Ihre Dokumente mit GitHub-Seiten kostenlos hosten, sondern auch andere Entwickler können so ganz einfach Pull-Anfragen an Ihre Dokumente senden, wenn sie auf Tippfehler oder andere Probleme stoßen. Wenn Sie GitHub nicht verwenden möchten, können Sie Ihre Dokumente natürlich auch anderswo hosten. • RTL-Unterstützung für linksläufige Sprachen wie Arabisch, Persisch (Farsi), Hebräisch usw. Verdikt Slate ist eine der leistungsstärksten Open-Source-Software zum Erstellen der Dokumentation. Gemäß den Gesprächen mit meinem Mentor Chris Myers werde ich Slate für Teil 4 und für andere Teile verwenden: GitHub und Markdown. In den folgenden Abschnitten wird die Dokumentation ausführlicher beschrieben. Struktur für die vorgeschlagene Dokumentation Ich habe eine Struktur für das SynBioHub-Nutzerhandbuch auf Seite 2 erstellt. Dieses Gebäude wird akzeptiert und bereits von Herrn Myers geändert. Projektziele 1. Dokumentation neu strukturieren 2. Aktualisieren Sie die Dokumentation, damit sie zu den aktuellen Versionen von SynBioHub passt. 3. Entfernen Sie veraltete Informationen. 4. Die Nutzerdokumentation überarbeiten, um sie leichter verständlich zu machen. 5. Ergänze die Dokumentation für neue Mitwirkende mit kurzen Voraussetzungen, um ihr grundlegendes Verständnis der grundlegenden biologischen Konzepte und der Benutzeroberfläche von SynBioHub zu verbessern.