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:
- SymPy
- Technischer Redakteur:
- Soumi7
- Projektname:
- Konsistenz über Dokumentstrings – Sympy-Dokumentation
- Projektdauer:
- Standardlänge (3 Monate)
Projektbeschreibung
Zusammenfassung :
Aktueller Stand der Sympy-Dokumentation und bisherige Arbeit :
Die Erstellung eines offiziellen Styleguides für SymPy ist abgeschlossen.
Im Rahmen ihres GSoD-Projekts hat Lauren Glattly einen Styleguide für SymPy-Docstrings erstellt, der unter SymPy Documentation Style Guide zu finden ist.
Die docstrings im speziellen Untermodul und die Datei „lösers.py“ wurden so bearbeitet, dass sie den Richtlinien des neuen Styleguides entsprechen.
Alle anderen Docstrings in der Codebasis mussten noch so bearbeitet werden, dass sie dem neuen Styleguide entsprechen.
Vorgeschlagene Arbeit :
Die meisten docstrings in SymPy entsprechen noch nicht dem aktuellen Styleguide. Ziel dieses Projekts wäre es, die docstrings in SymPy gemäß diesem Leitfaden zu aktualisieren.
Ich habe das Projekt mit Mentoren besprochen. Hier ist der Link zur Diskussion.
Es wurde entschieden, dass das Bearbeiten von Docstrings in der gesamten Codebasis von Sympy gemäß dem neuesten Styleguide eine große Aufgabe ist und das Projekt darauf beschränkt werden sollte.
Meine Arbeit am Projekt würde die Implementierung des neuen Leitfadens zur Aktualisierung vorhandener Docstrings umfassen, während andere Inkonsistenzen wie Sprachgebrauch oder Begriffe erfasst und behoben werden.
Die Reihenfolge der vorhandenen Unterabschnitte kann später oder als separate Aufgabe geändert werden.
Die Unterschiede bei den Ergebnissen, wenn verschiedene Werte an Parameter übergeben werden, werden durch zusätzliche Beispiele und einen Abschnitt zu Parametern veranschaulicht.
Fügen Sie dem Abschnitt zu Fallstricken und Stolpersteinen immer wieder knifflige Beispiele hinzu.
Beiträge: - #17887 : An Problem #17887 gearbeitet: Fehlende Abschnitte für Docstrings im Untermodul „Special“ hinzufügen. Ich habe in einigen Funktionen des Untermoduls „Specials“, das von L. bearbeitet wurde, den Abschnitt „Fehlende Parameter und Beispiele“ hinzugefügt. Glattly entspricht dem neuesten Styleguide und dient als Modell für zukünftige Docstrings.
Hier ist der Link zu meinem zusammengeführten PR : https://github.com/sympy/sympy/pull/19334
- #19591 : In Problem 19591 wird der Styleguide für die Dokumentation verfolgt. Ich habe einen PR-Team hinzugefügt, um den „core.sympify“-Dokumentstring so zu bearbeiten, dass er dem neuesten Styleguide entspricht. Ich habe strukturierte Erklärungen und Beispiele für die Verwendung verschiedener Parameter hinzugefügt.
Hier ist ein Link zum PR: https://github.com/sympy/sympy/pull/19613
Projektziele
Zeitplan Vor dem 17. August :
- Leisten Sie weiterhin einen Beitrag zur Organisation.
- Machen Sie sich mit der Nutzerdokumentation und der aktuellen Version von Sympy vertraut.
- Sie lernen Techniken und Fähigkeiten, die Ihnen bei der Implementierung des Projekts helfen werden.
Community-Bindung : (17. August bis 13. September 2020)
- Richten Sie einen Kommunikationskanal und eine Uhrzeit ein (aufgrund der Zeitverschiebung).
- Meine Ziele verfeinern und Erwartungen auf beiden Seiten formulieren.
- Sie besprechen die Reihenfolge, in der die Module aktualisiert werden.
- Schließen Sie die Reihenfolge der Bearbeitungsmodule ab, damit sie dem aktuellen Styleguide für Docstrings entsprechen.
Dokumentationszeitraum(14. September 2020 bis 30. November 2020) :
Legen Sie Ziele fest, die jede Woche erreicht werden sollen. Führen Sie am besten die Aktualisierung der docstrings für ein Modul oder Submodul pro Woche oder mehr durch.
Bei allen diesen Modulen besteht mein Hauptziel darin, fehlende Abschnitte hinzuzufügen und die Docstrings so umzustrukturieren, dass sie dem aktuellen Styleguide entsprechen. Dabei werden auch die unterschiedlichen Ergebnisse gezeigt, die sich ergeben, wenn den Parametern unterschiedliche Werte übergeben werden. Alle schwierigen Ergebnisse werden dem Abschnitt „Fallstricke und Fallschatten“ hinzugefügt.
Woche 1 ( 14. bis 21. September) : Kern
Woche 2 (22. bis 29. September) : Funktionen – Untermodule : Kombinatorische Logik
Woche 3 (30. September bis 6. Oktober) : Funktionen
Woche 4 (7. Oktober bis 14. Oktober) : Vereinfachen, Kryptowährungen
Woche 5 (15. bis 21. Oktober) : Diophantische Gleichungen
Woche 6 (22. Oktober bis 29. Oktober):Holonomic :Operations-Submodul
Woche 7 (30. Oktober bis 7. November) : Modul „Integrale“ (integrals.integrals), Integrale mit Meijer-G-Funktionen berechnen
Woche 8 (8. November bis 15. November) : Physik, Funktionen am Ende des Moduls „Kategorien“, Modul zur Codegenerierung, Spezialuntermodul
Woche 9 (16. November bis 23. November) : Physik, Funktionen am Ende des Kategorienmoduls, Codegenerierungsmodul, Untermodul „Spezial“
10. Woche (24. November bis 30. November) : Erwischen und Fallstricke
30. November bis 5. Dezember 2020 um 18:00 Uhr (UTC): endgültige Projektübermittlung und Erstellung von Berichten
3. bis 10. Dezember 2020 um 18:00 Uhr (UTC): Einreichen von Informationen zum Projekterfolg und zur Zusammenarbeit mit Mentoren
Die Reihenfolge der hier genannten Module kann nach weiteren Gesprächen mit Mentoren geändert werden.
Wie von den Mentoren vorgeschlagen, werde ich mich zuerst auf die Module konzentrieren, die sich leichter aktualisieren lassen, und dann zu den komplexeren übergehen.
Warum bin ich die richtige Person für dieses Projekt?
Ich glaube, dass ich die richtige Person für dieses Projekt bin, da ich bereits Erfahrung im technischen Schreiben im Bereich Informatik habe und mit git und github vertraut bin.
Da ich PRs eingereicht habe, um die Dokumentation auf den neuesten Styleguide in Sympy zu aktualisieren, die erfolgreich zusammengeführt wurden, bin ich mit dem Workflow vertraut und trage regelmäßig Beiträge ein.
Als ich anfing, Beiträge zu leisten, traten einige Fehler auf. Ich habe mir schließlich angewöhnt, die Tests auszuführen und die Dokumente jedes Mal zu erstellen, bevor ich die Änderungen übernehme, da dies sehr wichtig ist.
Ich freue mich sehr, an diesem Projekt mitzuwirken.