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
- moja global
- Pisarz techniczny:
- Tlazypanda
- Nazwa projektu:
- Dokumentacja przewodnika wprowadzającego w temat techniczny FLINT
- Długość projektu:
- Standardowa długość (3 miesiące)
Opis projektu
Dokumentacja Przewodnika po konfiguracji technicznej FLINT, który pomoże nowym współtwórcom przejść przez proces konfiguracji technicznej, dzięki czemu będą mogli łatwo rozpocząć pracę z minimalnym wsparciem ze strony administratorów.
Problemy z projektem
Oto lista najważniejszych problemów związanych z obecną dokumentacją: - Nieuporządkowane instrukcje w lokalnym przewodniku utrudniające rozpoczęcie pracy przez nowych współtwórców. – Wiele repozytoriów FLINT nie zawiera dokumentacji dotyczącej ich przeznaczenia i nie są ze sobą powiązane, co utrudnia nowemu użytkownikowi odnalezienie repozytorium do zainstalowania. – Instalacja w systemie Windows jest dobrze udokumentowana, ale dokumentacja instalacji w systemie Linux wymaga poprawek. – Proces Git nie jest obecnie uwzględniony w dokumentacji.
Proponowane rozwiązanie
Ta propozycja przedstawia rozwiązanie, które pomoże nowym współtwórcom przejść przez proces wprowadzenia technicznego, aby mogli oni łatwo rozpocząć pracę z minimalnym wsparciem ze strony administratorów. Możesz to osiągnąć, refaktoryzując bieżącą dokumentację w taki sposób, aby była dla początkujących przyjazna dla początkujących, oraz używaj centralnego, niezależnego repozytorium z całą dostępną dokumentacją. Projekt dzieli się na 3 etapy: – Sprawdzenie istniejącej dokumentacji i refaktoryzacja: na tym etapie chcemy przejrzeć bieżący przewodnik i zrefaktoryzować go w sposób zwięzły i zrozumiały dla nowych użytkowników. Należy też zmodyfikować dokumentację, aby była bardziej czytelna dla początkujących użytkowników, dodając plakietki, emotikony i informacje o problemach oznaczonych tagami „Tylko dla nowych użytkowników” lub „Dobrymi pierwszymi problemami”. – Utwórz centralne samodzielne repozytorium dokumentacji: celem tej fazy jest połączenie całej dostępnej dokumentacji w logicznej kolejności w samodzielnym repozytorium. Obejmuje to zamówienie wytycznych dotyczących publikowania treści, instrukcji konfiguracji projektu i instrukcji krok po kroku. – Dodanie przepływu pracy i witryny społeczności dla nowych programistów: w tym etapie należy dodać przepływ pracy programisty, który zawiera wytyczne dotyczące udostępniania aplikacji przez git, architekturę techniczną projektu oraz wskazówki dotyczące testowania i kontroli jakości. Proponowana strona społeczności będzie aplikacją jednostronicową wyświetlającą przepływ pracy, problemy dla początkujących, które mogą być przypisane nowym wolontariuszom, oraz listę wszystkich wolontariuszy. Etap 1. Sprawdź istniejącą dokumentację i przerób:
Zmodyfikuj bieżącą dokumentację tych repozytoriów: - FLINT: obecna dokumentacja nie jest zbyt szczegółowa i nie podaje sekwencyjnego porządku wymaganych bibliotek. Szczegółowe instrukcje są podzielone na różne pliki PDF, ale można je połączyć w jednym miejscu w bardziej zwięzłej formie. Poza tym przewodniki instalacyjne dotyczą systemu Windows, ale w przypadku Linuksa przekierowywanie do repozytorium FLINT.docker może okazać się pomocne. – FLINT.docker: obecna dokumentacja nie podaje celu utworzenia tego repozytorium, którym jest udostępnienie instalacji FLINT w systemie Linux za pomocą dockera. Obsługa w Dockerze jest ograniczona tylko do Ubuntu 18.04 (Bionic Beaver), ale można ją rozszerzyć na inne dystrybucje Linuksa. Obecna dokumentacja musi też kładć nacisk na sekwencyjny sposób konfigurowania plików Dockerfile oraz zawierać wystarczającą ilość informacji o generowaniu z pliku makefile. – FLINT.example: obecna dokumentacja nie podaje celu ustawienia tego repozytorium, którym jest przedstawienie przykładu użycia narzędzia FLINT. Różne próbki można lepiej oddzielić, podając konkretne instrukcje ich uruchamiania. Musimy też połączyć to repozytorium z głównym repozytorium FLINT, aby użytkownicy mogli się do niego dostać i zobaczyć przykład w akcji.
Do bieżącej dokumentacji należy dodać te informacje: - korzystanie z Git i GitHub: krok po kroku opisujemy w niej, jak rozwidlać, skopiować i skonfigurować zdalne źródło repozytorium. Znajdziesz w nim również informacje na temat sposobów bazowania na najnowszej wersji głównej i rozwiązywania konfliktów podczas scalania. – Plakietki i emotikony: obecna dokumentacja nie zawiera plakietek ani emotikonów, które mogłyby pomóc nowym wolontariuszom poczuć się mile widzianymi i mniej przerażonymi problemami. – informacje o problemach dla początkujących i osób, które dopiero zaczynają przygodę z programowaniem: pomogą one przekierować nowych współtwórców do problemów dla początkujących i na stronę społeczności. – Informacje o repozytorium Import-me: repozytorium Import-me jest szablonem bazowym do szybkiego uruchamiania dowolnego repozytorium Moja Globalne. Obecna dokumentacja nie wspomina o istocie tego problemu. Musi zostać zaktualizowany, aby zawierać wzmiankę o repozytorium Import-me. Należy też dodać instrukcje dotyczące wybierania go jako szablonu podczas tworzenia nowego repozytorium. Powinien też istnieć ustalony proces umożliwiający programistom sugerowanie dodatkowych funkcji dla repozytorium Import-me.
Etap 2. Utwórz centralne, niezależne repozytorium dokumentacji:
Narzędzie do hostowania platformy:
Proponowane narzędzia na tej platformie hostingowej to Read The Docs z tych powodów: – Automatyczne aktualizowanie po przesłaniu commita – Łatwe konfigurowanie i rozwiązywanie problemów dzięki dużej społeczności – Dokumentacja jest formatowana za pomocą reStructuredText, a wyjście jest kompilowane przez Sphinx.
Uporządkuj wszystkie treści w logiczny sposób:
Proponowana kolejność treści:- - Wprowadzenie do dokumentacji dla programistów: w tej sekcji znajdziesz wprowadzenie do Moja Global i FLINT. – Współpraca: ta sekcja będzie zawierać podsekcje „Sposoby na wniesienie wkładu” (w zakresie kodu, zgłaszania błędów, tłumaczenia, dokumentacji, organizacji wydarzeń itp.) oraz „Kodeks postępowania”. – Konfiguracja programisty: ta sekcja będzie zawierać podsekcje „Git i przepływ pracy w GitHub”, „Instalacja w Windows” i „Instalacja w Linuxie”. – Przepływ pracy dewelopera: ta sekcja będzie zawierać informacje o narzędziach zintegrowanych do testowania oraz o tym, jak przeprowadzić ręczne testowanie żądania pull request. Więcej informacji znajdziesz w dokumentacji z następnej fazy. – Dołącz do nas: w tej sekcji znajdziesz różne fora społecznościowe, takie jak kanały Slack, dzięki którym możesz nawiązać kontakt z Moja Global i z nimi współpracować.
Etap 3. Dodaj przepływ pracy dewelopera i witrynę społeczności dla nowych współtwórców:
Dokumentacja dotycząca przepływu pracy programistów:
Dokumentacja procesu pracy dewelopera będzie zawierać te podsekcje:
- Wykorzystany stos techniczny/architektura i różne moduły w kodzie: dokumentacja umożliwiająca zapoznanie nowych współtwórców z zaimplementowanym stosem technologicznym, różne biblioteki i moduły bazy kodu.
- Zintegrowane narzędzia do testowania i sprawdzania zakresu: przedstawiamy nowych współtwórców narzędzi potoku CI/CD używanych do testowania, boty dotyczące zakresu i automatycznych kontroli jakości przeprowadzanych z ich kodu. Szkolenie będzie też wskazywać, z kim należy się skontaktować w przypadku niepowodzenia testu.
- Boty wykorzystywane do usprawniania przepływu pracy, np.Zulipbot: projektowanie szablonów treści dla botów i udostępnianie dokumentacji umożliwiającej użytkownikom ich zrozumienie, a nawet usprawnienie konfiguracji bota dzięki wkładowi.
- Ręczne testowanie i przesyłanie pull request: dokumentacja dotycząca ręcznego testowania pull request pod kątem określonych standardów oraz przesyłanie wyników w postaci zrzutów ekranu lub plików GIF podczas przesyłania pull request.
- Wytyczne dotyczące sprawdzania pull request, których powinni przestrzegać współtwórcy: wytyczne dotyczące oznaczania określonych zespołów do sprawdzenia i dodawania do pull request etykiet takich jak „wymaga sprawdzenia”, aby umożliwić administratorom odpowiadanie.
Witryna społeczności:
Witryna społeczności będzie zawierać te funkcje:
- Informacje o procesie: proces będzie składać się z sekwencji działań, które nowy współtwórca może rozpocząć, np.zgłoszenie problemu dla początkujących, a następnie utworzenie problemu dla początkujących dla kogoś innego i pomoc innym przez udzielanie opinii i sprawdzanie ich pull requestów.
- Lista problemów dotyczących tylko pierwszego etapu: lista problemów przeznaczonych dla osób rozpoczynających korzystanie z aplikacji i nowych współtwórców.
- Lista nieaktualnych problemów: lista problemów, nad którymi od dłuższego czasu nie były rozwiązywane problemy, dlatego są dostępne do wybrania przez współtwórców.
- Lista współtwórców: lista współtwórców, którzy do tej pory przekazali darowiznę do repozytoriów Moja Global.
- Ostatni współtwórcy: lista współtwórców, którzy niedawno przekazali darowiznę do repozytoriów Moja Global.
- Linki umożliwiające dołączenie do forów czatu: informacje i linki umożliwiające dołączenie do społeczności Slacka, gdzie możesz odpowiadać na pytania i prowadzić dalsze dyskusje nad projektami.