projekt DIPY

Ta strona zawiera szczegółowe informacje na temat projektu technicznego przyjęta do programu Sezon Dokumentów Google.

Podsumowanie projektu

Organizacja open source:

DIPY

Pisarz techniczny:

Areesha Tariq

Nazwa projektu:

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

Długość projektu:

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

Opis projektu

Jestem inżynierem oprogramowania i doświadczeniem 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 to do 18 sierpnia. Brałem udział w sezonie Dokumentów Google jako autor techniczny w organizacji OpenELIS Global. Oryginalna dokumentacja była w języku francuskim, w ograniczonym zakresie i była nieaktualna. Przygotowałam więc obszerną i zaktualizowaną dokumentację w języku angielskim. W okresie maj–sierpień 2020 roku jestem deweloperem serwera Open Food Facts w organizacji Perl & Raku. Jednym z głównych zadań tego stażu jest tworzenie dokumentacji modułów i funkcji w formacie POD. Zetknęłam się z światem open source w zeszłym roku, gdy brałam udział w kilku projektach open source, a później uczestniczyłam w sezonie Dokumentów Google. W tym roku znalazłem się w inicjatywie Outline, która wspiera różnorodność w modelu open source i w bezpłatnym oprogramowaniu. Bardzo dobrze radzę sobie z GitHubem, ponieważ mój projekt Outline jest organizowany na GitHubie, a od marca regularnie uczestniczę w programie Open Food Facts i Mozilli Fenix. Jestem użytkownikiem systemu Linux od ponad 3 lat i od tego czasu używam poleceń terminala.

Narzędzia do dokumentacji i języki to: Sphinx, Przeczytaj dokumentację i Markdown. Spodobał mi się ten pomysł i chcę nad nim pracować, ponieważ mam odpowiednie doświadczenie i chciałbym wykorzystać swoją wiedzę i umiejętności, aby rozwijać DIPY. Mam doświadczenie w dziedzinie cyfrowego przetwarzania obrazu, rozpoznawania obrazów i systemów uczących się. Pomoże mi to lepiej zrozumieć neuroobrazowanie i przygotować dokumentację. Mam duże doświadczenie w dziedzinie medycyny. Stworzyłam witrynę medyczną dla lekarzy, pacjentów, laboratoriów i kierowców karetki pogotowia. Pracowałam nad innym systemem używanym przez lekarzy, pacjentów, pielęgniarek, asystentów laboratoryjnych i badaczy. Pomoże mi to w opracowaniu dokumentacji, która będzie bardziej zrozumiała dla odbiorców.

Przejrzałem(-am) dokumentację DIPY i zauważyłam w niej kilka niedoskonałości. W dokumentacji występuje wiele luk, które zamierzam poprawić. Obecny stan dokumentacji: Dokumentacja nie ma określonej struktury ani struktury Poruszanie się po witrynie może być uciążliwe i czasochłonne, zwłaszcza dla nowych użytkowników. Użytkownicy mogą mieć trudności ze uzyskaniem informacji z przewodnika. Należy poprawić treść dokumentacji. 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żytkownika były łatwo dostępne. Dokumentacja jest niespójna.

Planuję wykonać te czynności:

Opracowanie konkretnej struktury i szablonu dokumentacji Opracuj konkretną strukturę i szablon dokumentacji Opracuj dokumentację w taki sposób, aby użytkownicy mogli łatwo poruszać się po niej i jej znajdować wymagane informacje Usprawnij tworzenie planu działania lub listy elementów pracy w celu zaangażowania społeczności w dalszą pracę związaną z dokumentacją Definiowanie szablonów przewodnika użytkownika i przewodnika dla programistów Tworzenie szablonów do przewodnika Przepisywanie, reorganizacja i aktualizowanie przewodnika użytkownika, poradnika tworzenia i publikowania (które mogą pomóc i zmotywować nowych użytkowników do uczestniczenia w projekcie nietekstowym)

Przewodnik użytkownika:

W naszym przewodniku należy skupić się na prostym i zrozumiałym języku, który pomoże użytkownikom zrozumieć nawet najbardziej złożone systemy. Dla wygody użytkowników należy unikać żargonu, akronimów i innych informacji, których mogą nie znać nowi użytkownicy. Skupimy się też na korzystaniu z treści wizualnych, w tym obrazów, zrzutów ekranu z adnotacjami, grafik i filmów, które pozwalają szybko pokazać użytkownikowi, jak działa system. Dobra dokumentacja wymaga hierarchii nagłówków i podtytułów, dzięki którym użytkownik będzie wiedzieć, jakie informacje będą mu wyświetlane w poszczególnych sekcjach. Hierarchia ta powinna działać w sposób logiczny, aby ułatwić użytkownikowi nauczenie się korzystania z systemu w najbardziej przydatny sposób. Jednym z głównych celów tego projektu jest tworzenie łatwo dostępnych treści. Wszystkie dokumenty i przewodniki powinny mieć spójny styl. Stosowanie spójnych czcionek i kolorów uzupełniających w wielu dokumentach jest konieczne. Dopilnuję, aby użytkownicy mieli dostęp do większej ilości zasobów organizacji, które pomogą im odnieść sukces w korzystaniu z systemu.

Przewodnik dla programistów:

Przewodnik dla programistów zawiera szczegółowe 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, dzięki czemu możesz wybrać właściwą strategię w zależności od tego, co chcesz osiągnąć. Przewodnik dla programistów wymaga przekształcenia i przeorganizowania. Będę pisać na nowo treść przewodnika dla programistów. Materiały dotyczące budowania zależności, przewodniki stylistyczne, konwencje kodowania, przewodnik po dokumentacji, instalowanie środowiska programistycznego, debugowanie, przewodnik dotyczący testowania i inne informacje zostaną udostępnione deweloperom. Gdy nowi współtwórcy starają się szybko zająć Twój projekt, by po raz pierwszy opublikować treści na licencji open source, traktują te wskazówki jako wskazówki. Wytyczne będą czytelne, szczegółowe i przyjazne. Przewodniki dla użytkowników to przydatne dokumenty, które informują o tym, jak użytkownicy mogą wziąć udział w projekcie open source. Udział w projekcie powinien być łatwy i przejrzysty dla użytkowników, niezależnie od tego, czy chodzi o: przesyłanie poprawek, zgłaszanie błędów, dodawanie opiekuna, 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ć w zależności od wymagań dokumentu.

Udział w DIPY

• Wiadomość 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
• Nasze obowiązki
• Obowiązki osób odpowiedzialnych za projekt
• Zakres

Zakres Kodeksu postępowania

Co muszę wiedzieć, aby pomóc?

Jeśli chcesz pomóc we wdrożeniu kodu, nasz projekt używa [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 to the docs label or tag on your issue Tracker] lub z problemami z projektem [link to design label or tag on issue on issue on issue if your project śledzących problemy from the design]. Jeśli chcesz przekazać nasz kod i chcesz dowiedzieć się więcej o używanych przez nas technologiach, zapoznaj się z poniższą listą. Dołącz punktowaną listę zasobów (samouczków, filmów, książek), z których nowi współtwórcy mogą dowiedzieć się, co użytkownicy potrzebują, by wziąć udział w projekcie.

Konfigurowanie środowiska programistycznego

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

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

Jak dołączyć do projektu

Jak zgłosić błąd

• Przed wysł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 ulepszenia
• Jak przesłać (dobrą) sugestię dotyczącą ulepszenia?

Twoja pierwsza publikacja kodu

• Problemy dla początkujących
• Pomoc w razie problemów #### Żądanie pull
• Proces tworzenia żądania pull
• Upewnij się, że wszystkie kontrole stanu zostały zakończone.

Co zrobić, jeśli weryfikacja stanu zakończyła się niepowodzeniem?

• Pisanie testów
• Zakres testu

Przewodniki stylistyczne

• Komunikaty zatwierdzenia Git
• Styl standardowy

Pomoc

Jeśli masz problemy, daj nam znać. Jeśli potrzebujesz pomocy, możesz zadać pytanie na naszej liście adresowej, która znajduje się na stronie [e-mail], na czacie w IRC lub [podaj 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ę działać przez ponad 45 godzin tygodniowo, ale jeśli coś się nie stanie, odpłacę za te godziny w weekendy. W trakcie sesji więzi ze społecznością omówię sposoby komunikacji i sfinalizuję cotygodniowe spotkania, a także sposoby i czas na te spotkania z mentorem. Będę na bieżąco informować mentora o swojej pracy i przesyłać do niego szczegóły swojej pracy. Wolę aplikację TeamViewer do komunikacji, ponieważ jest łatwa w obsłudze i ma wiele funkcji, takich jak udostępnianie ekranu.