projekt DIPY

Ta strona zawiera szczegółowe informacje na temat projektu dotyczącego pisania technicznego zaakceptowanego do udziału w sezonie Dokumentów Google.

Podsumowanie projektu

Organizacja open source:

DIPY

Pisarz techniczny:

Areesha Tariq

Nazwa projektu:

Ogólna restrukturyzacja i skupienie się na użytkowniku

Długość projektu:

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

Opis projektu

Jestem inżynierem oprogramowania i 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 Islamabad w Pakistanie (strefa czasowa: UTC + 5). Obecnie pracuję jako stażysta w Contacty i potrwa do 18 sierpnia. Udzieliłem się w sezonie Dokumentów Google jako pisarz techniczny w organizacji OpenELIS Global. Oryginalna dokumentacja była w języku francuskim, ograniczona i nieaktualna. Przygotowałam więc obszerną i zaktualizowaną dokumentację dla użytkowników w języku angielskim. Wybraliśmy mnie do współpracy z Outline w organizacji Perl & Raku w okresie od maja do sierpnia 2020 roku jako wewnętrzny programista serwera Open Food Facts. Jednym z głównych zadań tego stażu jest opracowanie dokumentacji modułów i funkcji w formacie POD. W zeszłym roku zaczęłam pracować nad oprogramowaniem typu open source, gdy uczestniczyłam w kilku projektach open source, a później uczestniczyłam w sezonie Dokumentów Google. W tym roku zostałam wybrana do udziału w Outline, która wspiera różnorodność w zakresie oprogramowania open source i bezpłatnego oprogramowania. Bardzo dobrze radzę sobie z wykorzystaniem GitHuba, ponieważ mój projekt Outline jest hostowany na GitHubie, a od marca uczestniczę regularnie w organizacjach Open Food Facts i Mozilla Fenix. Jestem użytkownikiem systemu Linux od ponad 3 lat i od tego czasu używam poleceń terminala.

Używane przeze mnie narzędzia do dokumentacji i języki to: Sphinx, Przeczytaj dokumenty i Markdown. Podoba mi się ten pomysł i chcę nad nim popracować, ponieważ mam odpowiednie doświadczenie i chciałabym wykorzystać swoją wiedzę i umiejętności, aby pomóc w rozwijaniu kanału DIPY. Mam doświadczenie w dziedzinie przetwarzania obrazów cyfrowych, rozpoznawania obrazów i systemów uczących się. To pomoże mi lepiej zrozumieć neuroobrazowanie i ułatwi tworzenie dokumentacji. Mam duże doświadczenie w medycynie. Stworzyłem witrynę medyczną dla lekarzy, pacjentów, laboratoriów i kierowców karetek. Pracowałem nad innym systemem używanym przez lekarzy, pacjentów, pielęgniarze, pomocników laboratoryjnych i badaczy. Pomoże mi to w tworzeniu dokumentacji, która będzie bardziej zrozumiała dla odbiorców.

Przeczytałem dokumentację DIPY i zauważyłem kilka niedoskonałości w dokumentacji. W dokumentacji jest wiele luk, które zamierzam poprawić. Obecny stan dokumentacji: Dokumentacja nie ma określonej struktury i struktury. Poruszanie się po witrynie może być uciążliwe i czasochłonne, zwłaszcza dla nowych użytkowników. Uzyskiwanie informacji z przewodnika może być trudne. Treść dokumentacji wymaga ulepszenia. Jako nowy użytkownik miałem trudności z dostępem do przewodnika użytkownika i przewodnika dla programistów. Dokumentacja musi zostać zmieniona tak, aby informacje wymagane przez użytkowników były łatwo dostępne. Dokumentacja nie jest spójna.

Oto planowane działania:

Opracowanie konkretnej struktury i szablonu dokumentacji Modyfikowanie dokumentacji w taki sposób, aby użytkownicy mogli łatwo nawigować i znajdować wymagane informacje Opracowanie planu lub listy zadań w celu zaangażowania społeczności w dalszą pracę nad dokumentacją Tworzenie szablonów do publikacji Redagowanie, zmiana struktury i aktualizowanie przewodnika użytkownika, przewodnika dla programistów i przewodnika (którego mogą pomóc i zmotywować nowych użytkowników do dodawania obrazów niespójnych do projektu)

Przewodnik użytkownika:

W przewodniku użytkownika użyj prostego i prostego języka, aby ułatwić użytkownikom zrozumienie nawet najbardziej złożonych systemów. Aby zwiększyć wygodę użytkowników, unikaj żargonu, akronimów i innych informacji dla wtajemniczonych, których mogą nie znać nowi użytkownicy. Skupimy się też na używaniu treści wizualnych, w tym obrazów, zrzutów ekranu z adnotacjami, grafik i filmów, które szybko pokazują działanie systemu. Dobrze skonstruowana dokumentacja wymaga hierarchii nagłówków i podtytułów, dzięki którym użytkownik będzie wiedział, co zobaczą poszczególne sekcje. Hierarchia powinna działać w logiczny sposób, aby ułatwić użytkownikowi nauczenie się korzystania z systemu w najbardziej pomocny sposób. Jednym z głównych celów tego projektu jest tworzenie łatwo dostępnych treści. Wszystkie dokumenty i prowadnice są zgodne z spójnym stylem. Używanie spójnych czcionek i pasujących kolorów w wielu dokumentach jest niezbędne. Dopilnuję, aby użytkownicy mieli dostęp do większej ilości zasobów organizacji, dzięki którym mogą odnosić sukcesy z systemem.

Przewodnik dla programistów:

Przewodnik dla programistów zawiera obszerne wskazówki i materiały referencyjne, które mają pomóc deweloperowi w tworzeniu kodu źródłowego DIPY. Jego zadaniem jest przedstawienie różnych dostępnych opcji, co pozwoli Ci wybrać właściwą metodę w zależności od tego, co chcesz osiągnąć. Trzeba zmienić kształt i strukturę przewodnika. Będę pisać od nowa treść przewodnika dla programistów. Program obejmuje tworzenie zależności, przewodnik dotyczący tworzenia treści, poradnik stylistyczny, konwencje kodowania, przewodnik po dokumentacji, instalowanie środowiska programistycznego, debugowanie, przewodnik dotyczący testowania i inne podobne informacje, które są łatwo dostępne dla programistów. Gdy chętni nowi współtwórcy przyspieszają do Twojego projektu, aby dokonać swojej pierwszej wpłaty na licencji open source, traktują te wskazówki jako wskazówki. Wskazówki będą więc czytelne, wyczerpujące i przyjazne. Przewodniki to przydatne dokumenty, które informują, jak użytkownicy mogą wnieść swój wkład w projekt open source. Udział w projekcie powinien być jak najbardziej prosty i przejrzysty dla użytkowników: przesyłanie poprawek, zgłaszanie błędów, obsługa nadzoru, omawianie bieżącego stanu kodu, proponowanie nowych funkcji.

TEMPLATE

Jest to jeden z szablonów, których można użyć w przewodniku po darowiznach. Można go modyfikować, a sekcje dodawać i usuwać zgodnie z wymaganiami dokumentu.

Udział w projekcie DIPY

• Notatka powitalna

SPIS TREŚCI

Kodeks postępowania

• Nasze standardy
• Przykłady zachowań, które przyczyniają się do tworzenia pozytywnego środowiska
• Przykłady niedopuszczalnych zachowań uczestników
• Nasza odpowiedzialność
• Obowiązki osób odpowiedzialnych za projektowanie
• Zakres

Zakres Kodeksu postępowania

Co muszę wiedzieć, aby pomóc?

Jeśli potrzebujesz pomocy przy wprowadzaniu kodu, w naszym projekcie wykorzystamy [wstaw listę języków programowania, platform lub narzędzi, których używa Twój projekt]. Jeśli nie chcesz jeszcze przekazywać kodu, nie ma problemu. Możesz też zapoznać się z problemami z dokumentacją [link do etykiety dokumentów lub tagiem na swoim narzędziu do śledzenia problemów] lub z problemami z projektem [link to design label or tag on issue [link do etykiety projektu lub tagu w narzędziu do śledzenia problemów], jeśli projekt śledzi problemy z projektem]. Jeśli chcesz przekazać kod i dowiedzieć się więcej o używanych przez nas technologiach, zapoznaj się z listą poniżej. Dołącz punktowaną listę zasobów (samouczków, filmów, książek), z których nowi współtwórcy mogą dowiedzieć się więcej, aby wnieść swój wkład w projekt.

Konfigurowanie środowiska programistycznego

W tej sekcji dodam procedurę instalacji i zależności, które należy zainstalować. Zainstaluj projekt $project, uruchamiając polecenie: install project

• Kod źródłowy: github.com/$project/$project
• Issue Tracker: github.com/$project/$project/issues

Jak dołączyć do projektu

Jak zgłosić błąd

• Przed przesłaniem raportu o błędzie
• Jak przesłać (dobry) raport o błędzie?

Jak wprowadzić zmiany

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

Jak poprosić o ulepszenie

• Przed przesłaniem sugestii poprawy
• Jak przesłać (dobrą) propozycję ulepszenia?

Twoja pierwsza publikacja kodu

• Problemy dla początkujących
• Problemy wymagające pomocy #### Żądanie pull
• Proces tworzenia żądania pull
• Sprawdź, czy wszystkie kontrole stanu zostały zakończone.

Co się stanie, jeśli weryfikacja stanu zakończy się niepowodzeniem?

• Testy pisania
• Zakres testu

Przewodniki stylistyczne

• Komunikaty o zatwierdzeniach Git
• Styl standardowy

Pomoc

W razie problemów daj nam znać. Jeśli potrzebujesz pomocy, możesz zadać pytanie na naszej liście adresowej na adres: [e-mail], na czacie IRC lub [podać inne platformy komunikacyjne, z których korzysta Twój projekt].

Licencja

W tej sekcji znajdziesz informacje o licencji projektu.

Nakład pracy i komunikacja:

Będę realizować ponad 45 godzin w tygodniu, ale na wypadek, gdyby coś się stało, oddam mu wynagrodzenie w weekendy. W trakcie okresu więzi ze społecznością omówię środki komunikacji i sfinalizuję cotygodniowe spotkania, metody i czas spotkań z mentorem. Będę informować mentora na bieżąco o mojej pracy i przekażę mu e-maila z informacjami o moim zadaniu. Do komunikacji wolę używać TeamViewer, bo jest łatwy w obsłudze i ma wiele funkcji, np. udostępnianie ekranu.