DIPY-Projekt

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:
DIPY
Technischer Redakteur:
Areesha Tariq
Projektname:
Allgemeine Umstrukturierung und Fokus auf Endnutzer
Projektdauer:
Standarddauer (3 Monate)

Projektbeschreibung

Ich bin Softwareentwickler und habe Erfahrung im technischen Schreiben. Ich habe mehr als vier Jahre Erfahrung in der Erstellung hochwertiger Softwaredokumentationen, Benutzerhandbücher, Handbücher und Projektbeschreibungen. Ich lebe in Islamabad, Pakistan (Zeitzone: UTC + 5). Derzeit arbeite ich als Praktikant bei Outreachy, der noch bis zum 18. August andauert. Ich habe als Technical Writer bei der Organisation OpenELIS Global an der Google Season of Docs teilgenommen. Da die Originaldokumentation in französischer Sprache, nur eingeschränkt und veraltet war, habe ich eine umfassende und aktualisierte Endnutzerdokumentation auf Englisch erstellt. Ich wurde von Mai bis August 2020 in der Organisation Perl & Raku als Back-End-Entwickler des Open Food Facts-Servers ausgewählt. Neben der Back-End-Entwicklung besteht eine der Hauptaufgaben dieses Praktikums darin, die Dokumentation für Module und Funktionen im POD-Format zu erstellen. Letztes Jahr habe ich an einigen Open-Source-Projekten mitgewirkt und später an der Google Season of Docs mitgewirkt. Dieses Jahr wurde ich für Outreachy ausgewählt, das sich für mehr Diversität bei Open-Source-Software und kostenloser Software einsetzt. Ich kenne mich mit Git gut aus, da mein Outreachy-Projekt auf GitHub gehostet wird, und ich leite seit März regelmäßig Beiträge zu Open Food Facts und Mozilla Fenix. Ich verwende seit über 3 Jahren Linux-Nutzer und verwende seitdem Terminalbefehle.

Die Dokumentationstools und Sprachen, die ich verwendet habe, sind Sphinx, Read the docs, Markdown. Mir hat diese Idee gefallen und ich möchte daran arbeiten, weil ich relevante Erfahrung habe und mein Wissen und meine Fähigkeiten für DIPY einbringen möchte. Ich habe Erfahrung in den Bereichen digitale Bildverarbeitung, maschinelles Sehen, maschinelles Lernen. Sie hilft mir, die Neuroimaging-Technologie besser zu verstehen und die Dokumentation zu erstellen. Ich habe viel Erfahrung im medizinischen Bereich. Ich habe eine medizinische Website für Ärzte, Patienten, Labore und Krankenwagenfahrer entwickelt. Ich habe an einem anderen System gearbeitet, das von Ärzten, Patienten, Krankenschwestern, Laborassistenten und Forschern genutzt wird. Dies wird mir dabei helfen, eine Dokumentation zu erstellen, die für die Zielgruppe leichter verständlich ist.

Ich habe mir die DIPY-Dokumentation angesehen und mehrere Mängel notiert. Die Dokumentation enthält mehrere Schwachstellen, die ich verbessern möchte. Aktueller Stand der Dokumentation: Die Dokumentation hat keine bestimmte Struktur und kein spezielles Design. Die Navigation kann mühsam und zeitaufwändig sein, insbesondere für neue Nutzer. Nutzer finden es schwierig, Informationen aus dem Leitfaden zu erhalten. Der Inhalt der Dokumentation muss verbessert werden. Als neuer Nutzer hatte ich Schwierigkeiten, auf das Nutzerhandbuch und das Entwicklerhandbuch zuzugreifen. Dokumentation muss so umgestaltet werden, dass die für den Nutzer erforderlichen Informationen leicht zugänglich sein müssen. Die Dokumentation muss nicht einheitlich sein.

Ich habe vor, Folgendes zu tun:

Eine bestimmte Struktur und Vorlage für die Dokumentation definieren Die Dokumentation so umgestalten, dass die Nutzer leicht navigieren und die erforderlichen Informationen finden können Eine Roadmap oder eine Liste von Arbeitselementen erstellen, um die Community zur weiteren Dokumentationsarbeit einzubeziehen Vorlagen für das Nutzerhandbuch und den Entwicklerleitfaden definieren Vorlagen für die Erstellung von Anleitungen definieren Das Nutzerhandbuch, der Entwicklungsleitfaden und das Leitfaden mit Beiträgen neu schreiben, umstrukturieren und aktualisieren (das hilft und motiviert, neue Nutzer zur Verbesserung der Befehlszeilen-Dokumentation für neue Erläuterungstexte zu verbessern)

Nutzerhandbuch:

Beim Nutzerhandbuch würde ich mich auf die Verwendung einfacher, einfacher Sprache konzentrieren, damit die Nutzenden selbst die komplexesten Systeme verstehen können. Fachjargon, Akronyme und andere Insiderinformationen, die neue Nutzer möglicherweise nicht kennen, werden für eine bessere Nutzererfahrung vermieden. Ich werde mich außerdem auf die Verwendung visueller Inhalte wie Bilder, mit Anmerkungen versehene Screenshots, Grafiken und Videos konzentrieren, die den Nutzenden schnell zeigen, wie das System funktioniert. Eine gute Dokumentation erfordert eine Hierarchie aus Überschriften und Zwischenüberschriften, anhand derer Nutzende wissen, was in den einzelnen Abschnitten angezeigt wird. Diese Hierarchie sollte einem logischen Ablauf folgen, der den Nutzenden hilft, den Umgang mit dem System auf die hilfreichste Weise zu erlernen. Eines der Hauptziele dieses Projekts ist es, barrierefreie Inhalte zu erstellen. Alle Dokumente und Leitfäden entsprechen einem einheitlichen Stil. Die Verwendung einheitlicher Schriftarten und Komplementärfarben in mehreren Dokumenten ist ein Muss. Ich werde dafür sorgen, dass die Nutzenden Zugriff auf weitere Ressourcen des Unternehmens haben, um mit dem System erfolgreich zu sein.

Entwicklerleitfaden:

Das Entwicklerhandbuch enthält umfassende Anleitungen und Referenzmaterialien, die dem Entwickler dabei helfen, Beiträge zum DIPY-Quellcode zu erstellen. Dabei wird versucht, die verschiedenen Optionen darzustellen, die Ihnen zur Verfügung stehen, damit Sie je nachdem, was Sie erreichen möchten, den richtigen Ansatz wählen können. Der Entwicklungsleitfaden muss umgestaltet und umstrukturiert werden. Ich werde den Inhalt des Entwicklerhandbuchs umformulieren. Erstellung von Abhängigkeiten, Leitfaden, Styleguide, Codierungskonventionen, Dokumentation, Installation der Entwicklungsumgebung, Fehlerbehebung, Testanleitung und ähnliche Inhalte werden enthalten und für die Entwickler leicht zugänglich gemacht. Wenn eifrige neue Beitragende zu deinem Projekt vorbeikommen, um ihren ersten Open-Source-Beitrag zu leisten, stützen sie sich auf die Beitragsrichtlinien. Die Richtlinien sind daher leicht verständlich, ausführlich und freundlich. Beitragsleitfäden sind hilfreiche Dokumente, die kommunizieren, wie Personen zum Open-Source-Projekt beitragen können. Beiträge zum Projekt sollten für die Nutzer so einfach und transparent wie möglich gemacht werden, sei es: Einreichen einer Fehlerbehebung Melden eines Fehlers Erhalten eines Administrators Besprechen des aktuellen Status des Codes Vorschlagen neuer Funktionen

TEMPLATE

Dies ist eine der Vorlagen, die für den Beitragsleitfaden verwendet werden können. Es kann geändert und Abschnitte entsprechend den Anforderungen des Dokuments hinzugefügt oder entfernt werden.

Beitrag zu DIPY

  • Willkommenshinweis

TOC

Verhaltenskodex

  • Unsere Standards
  • Beispiele für Verhaltensweisen, die zur Schaffung einer positiven Umgebung beitragen
  • Beispiele für inakzeptables Verhalten von Teilnehmern
  • Unsere Pflichten
  • Verantwortlichkeiten der Projektbetreuer
  • Umfang

Geltungsbereich des Verhaltenskodex

Was muss ich wissen, um zu helfen?

Wenn Sie uns bei einem Codebeitrag helfen möchten, wird in unserem Projekt [Liste der Programmiersprachen, Frameworks oder Tools einfügen, die Ihr Projekt verwendet] verwendet. Wenn Sie noch nicht bereit sind, einen Codebeitrag zu leisten, ist das kein Problem. Sie können sich auch die Dokumentationsprobleme [link to the docs label or tag on your issue Tracker] oder die Probleme mit dem Design [link to design label or tag on issue Tracker if your project tracking design issues] ansehen. Wenn Sie einen Codebeitrag beitragen möchten und mehr über die von uns verwendeten Technologien erfahren möchten, sehen Sie sich die folgende Liste an. Fügen Sie eine Liste mit Ressourcen (Tutorials, Videos, Bücher) hinzu, die neue Beitragende verwenden können, um zu erfahren, was Nutzer wissen müssen, um einen Beitrag zum Projekt zu leisten.

Entwicklungsumgebung einrichten

In diesem Abschnitt füge ich das Installationsverfahren und die Abhängigkeiten hinzu, die installiert werden müssen. Installieren Sie $project mit dem Befehl „install project“

  • Quellcode: github.com/$project/$project
  • Problemverfolgung: github.com/$project/$project/issues

So kannst du Fragen beantworten

Fehler melden

  • Vor dem Einreichen eines Fehlerberichts
  • Wie reiche ich einen (guten) Fehlerbericht ein?

Änderungen einreichen

  • Pull-Anfrageprotokolle
  • Antwort des Teams
  • Reaktionsgeschwindigkeit

Erweiterung beantragen

  • Vor dem Einreichen eines Verbesserungsvorschlags
  • Wie reiche ich einen (guten) Korrekturvorschlag ein?

Ihr erster Codebeitrag

  • Probleme für Anfänger
  • Hilfe zu gewünschten Problemen #### Pull-Anfrage
  • Prozess zum Erstellen der Pull-Anfrage
  • Prüfen Sie, ob alle Statusprüfungen bestanden wurden.

Was passiert, wenn die Statusprüfungen fehlschlagen?

  • Schreiben von Tests
  • Testabdeckung

Stilrichtlinien

  • Git-Commit-Nachrichten
  • Standardstil

Support

Falls Probleme auftreten, wenden Sie sich bitte an uns. Wenn Sie Hilfe benötigen, können Sie Fragen über unsere Mailingliste unter project@google-groups.com, IRC-Chat oder [alle anderen von Ihrem Projekt verwendeten Kommunikationsplattformen auflisten].

Lizenz

In diesem Abschnitt finden Sie Informationen zur Lizenz des Projekts.

Zeitaufwand und Kommunikation:

Ich werde mehr als 45 Stunden pro Woche einplanen, aber im Falle eines Missverständnisses werde ich diese Stunden an Wochenenden entschädigen. Während der Phase der Gemeinschaft werde ich die Kommunikationswege besprechen und die wöchentlichen Treffen, Mittel und Zeiten für diese Treffen mit meinem Mentor festlegen. Ich werde meinen Mentor über meine Arbeit auf dem Laufenden halten und meine Arbeitsdetails per E-Mail an ihn weiterleiten. Ich bevorzuge Team Viewer für die Kommunikation, da er einfach zu nutzen ist und viele Funktionen hat, z. B. Bildschirmfreigaben.