projekt DIPY

Ta strona zawiera szczegółowe informacje o projekcie polegającym na pisaniu tekstów technicznych, który został zaakceptowany w ramach Google Season of Docs.

Podsumowanie projektu

Organizacja open source:

DIPY

Pisarz techniczny:

Areesha Tariq

Nazwa projektu:

Restrukturyzacja na wysokim poziomie i skupienie się na użytkowniku końcowym

Długość projektu:

Standardowa długość (3 miesiące)

Opis projektu

Jestem programistą i mam doświadczenie w pisaniu tekstów technicznych. Mam ponad 4 lata doświadczenia w tworzeniu wysokiej jakości dokumentacji oprogramowania, przewodników użytkownika, podręczników i opisów projektów. Mieszkam w Islamabadzie w Pakistanie (strefa czasowa: UTC + 5). Obecnie pracuję jako stażystka w Outreachy. Będę tam pracować do 18 sierpnia. Brałam udział w Google Season of Docs jako autorka tekstów technicznych w organizacji OpenELIS Global. Pierwotna dokumentacja była dostępna tylko w języku francuskim, była ograniczona i nieaktualna, więc utworzyłem obszerną i zaktualizowaną dokumentację dla użytkowników końcowych w języku angielskim. Zostałem wybrany w ramach Outreachy w organizacji Perl & Raku na okres od maja do sierpnia 2020 r. jako programista backendu serwera Open Food Facts. Oprócz tworzenia backendów jednym z głównych zadań tego stażu jest tworzenie dokumentacji do modułów i funkcji w formacie POD. W zeszłym roku zaczęłam zajmować się oprogramowaniem open source, gdy wniosłam swój wkład w kilka projektów open source, a później wzięłam udział w Google Season of Docs. W tym roku zostałam wybrana do programu Outreachy, który wspiera różnorodność w oprogramowaniu open source i free software. Bardzo dobrze pracuję nad Git, ponieważ mój projekt Outreachy jest hostowany na platformie GitHub. Od marca regularnie biorę udział w projektach Open Food Facts i Mozilla Fenix. Korzystam z Linuksa od ponad 3 lat i od tego czasu używam poleceń terminala.

Używane przeze mnie narzędzia i języki do tworzenia dokumentacji to Sphinx, Read the docs i Markdown. Podoba mi się ten pomysł i chcę nad nim pracować, ponieważ mam odpowiednie doświadczenie i chcę wykorzystać swoją wiedzę i umiejętności, aby przyczynić się do rozwoju projektu. Mam doświadczenie w zakresie przetwarzania cyfrowych obrazów, systemów wizyjnych i uczenia maszynowego. Pomoże mi to lepiej zrozumieć neuroobrazowanie i ułatwi tworzenie dokumentacji. Mam duże doświadczenie w dziedzinie medycznej. Stworzyłem witrynę medyczną dla lekarzy, pacjentów, laboratoriów i kierowców karetek. Pracowałem(-am) nad innym systemem używanym przez lekarzy, pacjentów, pielęgniarki, asystentów laboratoryjnych i naukowców. Pomoże mi to stworzyć dokumentację, która będzie łatwiejsza do zrozumienia dla odbiorców.

Po zapoznaniu się z dokumentacją firmy DIPY widzę kilka błędów. Dokumentacja zawiera wiele luk, które planuję poprawić. Obecny stan dokumentacji: Dokumentacja nie ma odpowiedniej struktury i projektu Poruszanie się po niej może być uciążliwe i czasochłonne, zwłaszcza dla nowych użytkowników. Użytkownicy mogą mieć trudności ze znalezieniem informacji z przewodnika Należy poprawić treść dokumentacji Jako nowy użytkownik miałem problem z dostępem do przewodnika użytkownika i przewodnika dla programistów. Dokumentacja musi zostać zmieniona w taki sposób, aby informacje wymagane przez użytkownika były łatwo dostępne. Dokumentacja jest niespójna

Zamierzam wykonać te czynności:

Określ konkretną strukturę i szablon dokumentacji. Zmień dokumentację tak, aby użytkownicy mogli łatwo się po niej poruszać i znajdować potrzebne informacje. Przygotuj plan lub listę elementów pracy, aby zachęcić społeczność do dalszego tworzenia dokumentacji. Określ szablony dla przewodnika użytkownika i przewodnika dla programistów. Określ szablony dla przewodnika dla autorów. Przepisz, przebuduj i zaktualizuj przewodnik użytkownika, przewodnik dla programistów i przewodnik dla autorów (które mogą pomóc i zmotywować nowych użytkowników do udziału w projekcie). Dodaj obrazy nietekstowe, aby wzbogacić tekstowe wyjaśnienia. Zwiększ spójność dokumentacji. Utwórz dokumentację dla nowego interfejsu wiersza poleceń.

Przewodnik użytkownika:

W przypadku przewodnika użytkownika warto używać prostego języka, aby ułatwić użytkownikom zrozumienie nawet najbardziej złożonych systemów. Żargon, akronimy i inne informacje, których nowi użytkownicy mogą nie znać, nie powinny być używane, aby nie zakłócać komfortu użytkowników. Skupię się też na treściach wizualnych, takich jak obrazy, opatrzone adnotacjami zrzuty ekranu, grafiki i filmy, które szybko pokazują użytkownikowi, jak działa system. Dobra dokumentacja wymaga hierarchii nagłówków i podnagłówków, która pozwala użytkownikowi dowiedzieć się, co zawiera każda sekcja. Hierarchia ta powinna funkcjonować zgodnie z logiką, która pomaga użytkownikowi nauczyć się korzystać z systemu w najbardziej pomocny sposób. Jednym z głównych celów tego projektu jest tworzenie treści dostępnych. Wszystkie dokumenty i poradniki powinny być utrzymane w spójnym stylu. Używanie spójnych czcionek i dopasowanych kolorów w wielu dokumentach jest niezbędne. Zadbam o to, aby użytkownicy mieli dostęp do większej liczby zasobów organizacji dotyczących korzystania z systemu.

Przewodnik dla programistów:

Przewodnik dla programistów zawiera obszerne wskazówki i materiały referencyjne, które pomogą deweloperowi w tworzeniu kodu źródłowego DIPY. Stara się on przedstawić różne dostępne opcje, aby umożliwić Ci wybór odpowiedniego podejścia zależnie od tego, co chcesz osiągnąć. Przewodnik dla programistów wymaga przekształcenia i restrukturyzacji. Napiszę nową wersję przewodnika dla programistów. Uwzględnione zostaną zależności budynków, przewodnik dotyczący współtworzenia aplikacji, przewodnik stylistyczny, konwencje kodowania, przewodnik z dokumentacją, instalacja środowiska programistycznego, debugowanie, przewodnik po testowaniu i powiązane zagadnienia, które będą łatwo dostępne dla programistów. Gdy nowi, pełni zapału kontributorzy rzucą się do Twojego projektu, aby w pełni wykorzystać możliwości open source, będą się kierować wskazówkami dla kontributorów. Wytyczne powinny być łatwe do przeczytania, wyczerpujące i przyjazne. Przewodniki dotyczące wkładu to przydatne dokumenty, które informują, jak można przyczynić się do projektu open source. Udział w projekcie powinien być dla użytkowników jak najprostszy i jak najbardziej przejrzysty, niezależnie od tego, czy chodzi o przesyłanie poprawek, zgłaszanie błędów, prowadzenie prac konserwacyjnych, omawianie bieżącego stanu kodu czy proponowanie nowych funkcji.

TEMPLATE

To jeden z szablonów, których można używać w przewodniku dotyczącym publikowania treści. Można go modyfikować, a także dodawać i usuwać sekcje zgodnie z wymaganiami dokumentu.

Współpraca z zespołem DIPY

• Wiadomość powitalna

TOC

Kodeks postępowania

• Nasze standardy
• Przykłady zachowań, które przyczyniają się do tworzenia pozytywnego środowiska
• Przykłady niedopuszczalnego zachowania uczestników
• Nasze obowiązki
• Obowiązki administratorów projektu
• Zakres

Zakres kodeksu postępowania

Co muszę wiedzieć, aby pomóc?

Jeśli chcesz pomóc w przyczynie z kodą, nasz projekt korzysta z [insert list of programming languages, frameworks, or tools that your project uses]. Jeśli nie czujesz się jeszcze gotowy/gotowa do wniesienia swojego wkładu w kody, nie ma problemu. Możesz też zapoznać się z problemami z dokumentacją [link to the docs label or tag on your issue tracker] oraz z naszymi problemami z projektem [link to design label or tag on issue tracker, jeśli Twój projekt śledzi problemy z projektem]. Jeśli chcesz przyczynić się do rozwoju kodu i dowiedzieć się więcej o technologiach, których używamy, zapoznaj się z listą poniżej. Uwzględnij listę zasobów (samouczków, filmów, książek) z odpowiednimi punktami, które nowi współtwórcy mogą wykorzystać, aby dowiedzieć się, co muszą wiedzieć, aby móc przyczynić się do projektu.

Konfigurowanie środowiska programistycznego

W tej sekcji dodam procedurę instalacji i zależne komponenty, które należy zainstalować. Instalowanie $project przez uruchomienie: install project

• Kod źródłowy: github.com/$project/$project
• Narzędzie do śledzenia problemów: github.com/$project/$project/issues

Jak dołączyć do projektu

Zgłaszanie błędów

• Zanim prześlesz raport o błędzie
• Jak przesłać (dobry) raport o błędzie?

Jak przesłać zmiany

• Protokoły żądań pull
• Odpowiedź zespołu
• Szybkość odpowiedzi

Jak poprosić o ulepszenie

• Zanim prześlesz sugestię ulepszenia
• Jak przesłać propozycję ulepszenia (dobrą)?

Twój pierwszy wkład w tworzenie kodu

• Problemy początkujących
• Pomoc w rozwiązywaniu problemów #### Żądanie pull
• Proces tworzenia prośby o pobranie
• Sprawdź, czy wszystkie testy stanu zostały zaliczone.

Co zrobić, jeśli sprawdzanie stanu się nie powiodło?

• Testy pisania
• Zakres testów

Prowadnice stylistyczne

• Komunikaty zatwierdzenia w Git
• Styl standardowy

Pomoc

Jeśli masz problemy, daj nam znać. Jeśli potrzebujesz pomocy, możesz zadawać pytania na naszej liście mailingowej pod adresem [e-mail], na czacie IRC lub na [wymień inne platformy komunikacyjne używane przez Twój projekt].

Licencja

W tej sekcji znajdziesz informacje o licencjach projektu.

Ilość czasu i komunikacja:

Będę pracować ponad 45 godzin tygodniowo, ale w przypadku jakiejś wpadki te godziny zostaną skompensowane w weekendy. W trakcie okresu budowania więzi ze społecznością będę omawiać sposoby komunikacji i ustalać z moim mentorem szczegóły cotygodniowych spotkań, w tym ich czas i formę. Będę na bieżąco informować mentora o mojej pracy, a szczegóły pracy prześlę mu e-mailem. Do komunikacji wolę używać TeamViewer, ponieważ jest on łatwy w użyciu i zawiera wiele funkcji, takich jak udostępnianie ekranu.