DIPY-Projekt

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:
DIPY
Technischer Redakteur:
Areesha Tariq
Projektname:
Gesamtstruktur und Fokus auf Endnutzer
Projektdauer:
Standardlänge (3 Monate)

Projektbeschreibung

Ich bin Software Engineer und über Expertise im technischen Bereich. Ich habe mehr als 4 Jahre Erfahrung in der Erstellung hochwertiger Softwaredokumentation, Nutzerhandbücher, Anleitungen und Projektbeschreibungen. Ich lebe in Islamabad, Pakistan (Zeitzone: UTC+5). Derzeit arbeite ich als Praktikantin bei Outreachy. Das Praktikum dauert noch bis zum 18. August. Ich habe an der Google Season of Docs als technischer Redakteur bei der Organisation OpenELIS Global teilgenommen. Die ursprüngliche Dokumentation war auf Französisch, begrenzt und veraltet, daher habe ich eine umfangreiche und aktualisierte Endnutzerdokumentation auf Englisch erstellt. Ich wurde von Outreachy in der Organisation Perl & Raku für den Zeitraum Mai bis August 2020 als Back-End-Entwickler des Open Food Facts-Servers ausgewählt. Neben der Backend-Entwicklung besteht eine der Hauptaufgaben dieses Praktikums darin, Dokumentationen für Module und Funktionen im POD-Format zu erstellen. Letztes Jahr kam ich in die Welt der Open Source, als ich an einigen Open-Source-Projekten mitgewirkt und später an der Google Docs-Saison teilgenommen habe. Dieses Jahr wurde ich bei Outreachy ausgewählt, der sich für Diversität bei Open-Source- und kostenloser Software einsetzt. Ich habe gute Kenntnisse mit Git, da mein Outreachy-Projekt auf GitHub gehostet wird und ich seit März regelmäßig Beiträge zu Open Food Facts und Mozilla Fenix leiste. Ich nutze seit mehr als 3 Jahren Linux und verwende seitdem Terminalbefehle.

Die von mir verwendeten Dokumentationstools und ‑sprachen sind Sphinx, Read the Docs und Markdown. Diese Idee hat mir gefallen und ich möchte daran arbeiten, weil ich einschlägige Erfahrung habe und mein Wissen und meine Fähigkeiten gerne nutzen würde, um zu DIPY beizutragen. Ich habe Erfahrung in den Bereichen digitale Bildverarbeitung, maschinelles Sehen und maschinelles Lernen. Sie wird mir helfen, die Neurobildgebung besser zu verstehen und Dokumentationen zu erstellen. Ich habe umfassende 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 verwendet wird. So kann ich eine Dokumentation erstellen, die für die Zielgruppe leichter verständlich ist.

Ich habe die Dokumentation von DIPY gelesen und mehrere Fehler darin notiert. Es gibt mehrere Lücken in der Dokumentation, die ich verbessern möchte. Aktueller Zustand der Dokumentation: Die Dokumentation hat keine bestimmte Struktur und kein bestimmtes Design Die Navigation kann vor allem für neue Nutzer mühsam und zeitaufwendig sein Nutzer haben möglicherweise Schwierigkeiten, Informationen aus dem Leitfaden zu erhalten Der Inhalt der Dokumentation muss verbessert werden Als neuer Nutzer fand ich es schwierig, auf die Bedienungsanleitung und den Entwicklerleitfaden zuzugreifen. Die Dokumentation muss so umgestaltet werden, dass die vom Nutzer benötigten Informationen leicht zugänglich sind. Die Dokumentation ist nicht einheitlich.

Ich habe folgende Schritte geplant:

Eine bestimmte Struktur und Vorlage für die Dokumentation definieren Formulieren Sie die Dokumentation so, dass Nutzer die erforderlichen Informationen leicht finden können. Erstellen Sie eine Roadmap oder eine Liste von Arbeitsaufgaben, um die Community bei weiteren Dokumentationsarbeiten einzubeziehen. Definieren Sie Vorlagen für das Nutzerhandbuch und den Entwicklerleitfaden Definieren Sie Vorlagen für beitragende Anleitung Das Nutzerhandbuch, die Entwicklungsanleitung und die beitragende Anleitung (die dabei helfen und neue Nutzer dazu motivieren können, zum Projekt beizutragen) Text in der Dokumentation verbessern

Nutzerhandbuch:

Für die Bedienungsanleitung würde ich einfache, verständliche Sprache verwenden, damit Nutzer auch die komplexesten Systeme verstehen können. Jargon, Akronyme und andere Insiderinformationen, die ein neuer Nutzer möglicherweise nicht kennt, werden vermieden, um die Nutzerfreundlichkeit zu verbessern. Außerdem werde ich mich auf visuelle Inhalte wie Bilder, mit Anmerkungen versehene Screenshots, Grafiken und Videos konzentrieren, die den Nutzern schnell zeigen, wie das System funktioniert. Eine gute Dokumentation benötigt eine Hierarchie von Überschriften und Zwischenüberschriften, die den Nutzern Aufschluss darüber gibt, was sie in den einzelnen Abschnitten erwartet. Diese Hierarchie sollte einem logischen Ablauf folgen, der den Nutzenden hilft, das System auf die hilfreichste Weise zu nutzen. Eines der Hauptziele dieses Projekts besteht darin, barrierefreie Inhalte zu erstellen. Alle Dokumente und Anleitungen sollten einem einheitlichen Stil folgen. Verwenden Sie in mehreren Dokumenten einheitliche Schriftarten und komplementäre Farben. Ich werde dafür sorgen, dass die Nutzer Zugriff auf mehr Ressourcen der Organisation erhalten, um mit dem System erfolgreich zu sein.

Entwicklerleitfaden:

Der Entwicklerleitfaden enthält umfangreiche Anleitungen und Referenzmaterialien, die Entwicklern beim Erstellen von Beiträgen zum Quellcode von DIPY helfen. Es werden die verschiedenen Optionen beschrieben, damit Sie je nach Zielvorhaben den richtigen Ansatz wählen können. Der Entwicklungsleitfaden muss neu gestaltet und umstrukturiert werden. Ich werde den Inhalt des Entwicklerhandbuchs umformulieren. Abhängigkeiten erstellen, Leitfaden für Beiträge, Styleguide, Codierungskonventionen, Dokumentationsleitfaden, Installation der Entwicklungsumgebung, Debugging, Testleitfaden und ähnliche Inhalte werden enthalten und für die Entwickler leicht zugänglich gemacht. Wenn engagierte neue Mitwirkende zu deinem Projekt eilen, um ihren ersten Open-Source-Beitrag zu leisten, können sie sich auf die Beitragsrichtlinien als Orientierungshilfe verlassen. Die Richtlinien sind dann leicht zu lesen, ausführlich und freundlich. Leitfäden für Mitwirkende sind hilfreiche Dokumente, die erklären, wie Nutzer zum Open-Source-Projekt beitragen können. Die Mitwirkung am Projekt sollte für die Nutzer so einfach und transparent wie möglich sein, z. B.: Verbesserungen einreichen Fehler melden Mitbetreuer werden Den aktuellen Zustand des Codes besprechen Neue Funktionen vorschlagen

TEMPLATE

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

Zu DIPY beitragen

  • Willkommensnachricht

TOC

Verhaltenskodex

  • Unsere Standards
  • Beispiele für Verhaltensweisen, die zu einer positiven Umgebung beitragen
  • Beispiele für unzulässiges Verhalten von Teilnehmern
  • Unsere Verantwortung
  • Verantwortlichkeiten der Projektleitung
  • Umfang

Geltungsbereich des Verhaltenskodex

Was muss ich wissen, um Ihnen helfen zu können?

Wenn Sie bei einem Codebeitrag helfen möchten, der in unserem Projekt verwendet wird [Liste der Programmiersprachen, Frameworks oder Tools einfügen, die in Ihrem Projekt verwendet werden]. Wenn Sie noch nicht bereit sind, Code beizutragen, ist das kein Problem. Sie können sich auch die Dokumentationsprobleme [Link zum Label oder Tag für die Dokumentation in Ihrem Issue Tracker] oder die Designprobleme ansehen, die wir haben [Link zum Label oder Tag für Designprobleme im Issue Tracker, falls Ihr Projekt Designprobleme erfasst]. Wenn du Code beisteuern und mehr über die von uns verwendeten Technologien erfahren möchtest, findest du in der folgenden Liste weitere Informationen. Fügen Sie eine Aufzählungsliste mit Ressourcen (Tutorials, Videos, Bücher) hinzu, anhand derer neue Mitwirkende erfahren können, was Nutzer wissen müssen, um zum Projekt beizutragen.

Entwicklungsumgebung einrichten

In diesem Abschnitt füge ich das Installationsverfahren und die zu installierenden Abhängigkeiten hinzu. Installieren Sie $project mit dem Befehl „install project“.

  • Quellcode: github.com/$project/$project
  • Issue Tracker: github.com/$project/$project/issues

So kannst du Fragen beantworten

Fehler melden

  • Bevor Sie einen Fehlerbericht senden
  • Wie sende ich einen guten Fehlerbericht?

Änderungen einreichen

  • Pull-Anfrageprotokolle
  • Antwort des Teams
  • Reaktionsgeschwindigkeit

Verbesserungen beantragen

  • Vor dem Einreichen eines Optimierungsvorschlags
  • How Do I Submit A (Good) Enhancement Suggestion?

Ihr erster Codebeitrag

  • Probleme für Anfänger
  • Probleme mit „Hilfe benötigt“ #### Pull-Anfrage
  • Pull-Anfrage erstellen
  • Prüfen Sie, ob alle Statusprüfungen bestanden wurden.

Was passiert, wenn die Statusprüfungen fehlschlagen?

  • Tests schreiben
  • Testabdeckung

Styleguides

  • Git-Commit-Nachrichten
  • Standardstil

Support

Bei Problemen können Sie sich gern an uns wenden. Wenn Sie Hilfe benötigen, können Sie Fragen in unserer Mailingliste unter project@google-groups.com, im IRC-Chat oder [andere Kommunikationsplattformen, die in Ihrem Projekt verwendet werden] stellen.

Lizenz

In diesem Abschnitt finden Sie Informationen zur Lizenz des Projekts.

Zeitaufwand und Kommunikation:

Ich werde mehr als 45 Stunden pro Woche arbeiten, aber im Falle eines Unfalls werde ich diese Stunden am Wochenende kompensieren. Während des Community Bond-Programms werde ich mit meinem Mentor über Kommunikationsmittel sprechen und wöchentliche Besprechungen, die Art der Kommunikation und die Zeit für diese Besprechungen festlegen. Ich halte meinen Mentor über meine Arbeit auf dem Laufenden und sende ihm meine Arbeitsdetails per E-Mail. Ich bevorzuge TeamViewer für die Kommunikation, da es einfach zu bedienen ist und viele Funktionen wie die Bildschirmfreigabe bietet.