Ta strona zawiera szczegółowe informacje na temat projektu technicznego przyjęta do programu Sezon Dokumentów Google.
Podsumowanie projektu
- Organizacja open source:
- moja globalna
- Pisarz techniczny:
- Tlazypanda
- Nazwa projektu:
- Dokumentacja technicznego przewodnika wprowadzającego do języka FLINT
- Długość projektu:
- Standardowa długość (3 miesiące)
Opis projektu
Dokumentacja technicznego przewodnika wprowadzającego dla pracowników pierwszej linii dla FLINT, która pomoże nowym współtwórcom w kwestiach technicznych, aby ułatwić rozpoczęcie pracy przy minimalnym wsparciu personelu.
Problemy związane z projektem
Oto lista najważniejszych problemów związanych z obecną dokumentacją: – Nieuporządkowane fragmenty instrukcji konfiguracji lokalnej, które utrudniają nowym współtwórcom rozpoczęcie korzystania z usługi. – W wielu repozytoriach FLINT nie ma dokumentacji dotyczącej ich przeznaczenia i nie są ze sobą połączone, co utrudnia nowemu użytkownikowi określenie, które repozytorium ma zainstalować. - Instalacja w systemie Windows jest dobrze udokumentowana, ale w dokumentacji dotyczącej systemu Linux można wprowadzić ulepszenia. - Przepływ pracy Git nie jest obecnie częścią dokumentacji.
Proponowane rozwiązanie
Ta oferta stanowi rozwiązanie do przeprowadzenia nowych współtwórców przez wprowadzenie techniczne, tak aby nowi współtwórcy mogli łatwo rozpocząć pracę z minimalnym wsparciem ze strony opiekunów. Można to osiągnąć, refaktoryzując bieżącą dokumentację, dzięki czemu jest ona przyjazna dla początkujących. Dodatkowo można utworzyć centralne, oddzielne repozytorium dla całej dostępnej dokumentacji. Projekt jest podzielony na 3 fazy: – Przegląd istniejącej dokumentacji i refaktoryzacja: celem tego etapu jest przejrzenie bieżącego przewodnika i jego refaktoryzowanie w taki sposób, aby był on zwięzły i zrozumiały dla nowych uczestników. Należy też zmodyfikować dokumentację, aby była bardziej przydatna dla początkujących. Dodamy w niej plakietki, emotikony i informacje dotyczące problemów oznaczonych tagami przeznaczonymi tylko dla nowych użytkowników lub tagami problemów z pierwszej ręki. – Utwórz centralne, samodzielne repozytorium dokumentacji: celem tego etapu jest połączenie w logicznej kolejności całej dokumentacji dostępnej w samodzielnym repozytorium. Polega to na ustaleniu wytycznych dotyczących darowizn, instrukcji konfiguracji projektu i szczegółowych przewodników. – Dodanie przepływu pracy programisty i witryny społeczności dla nowych programistów: celem tego etapu jest dodanie przepływu pracy programisty, który zawiera wytyczne git rojs, architekturę technologiczną projektu oraz wskazówki dotyczące testowania i kontroli jakości. Proponowana witryna społeczności jest aplikacją jednostronicową zawierającą informacje o przepływie pracy, problemach, które użytkownicy mogą zgłosić po raz pierwszy, oraz listę wszystkich współtwórców. Etap 1. Przejrzyj istniejącą dokumentację i refaktoryzację:
Wprowadź zmiany w bieżącej dokumentacji następujących repozytoriów: – FLINT: obecna dokumentacja nie jest zbyt szczegółowa i nie zawiera sekwencyjnej wymaganej biblioteki wstępnych. Szczegółowe instrukcje są podzielone na różne pliki PDF, ale możesz je znaleźć w jednym miejscu w bardziej zwięzły sposób. Przewodniki instalacji dotyczą też systemu Windows, ale w przypadku instalacji w systemie Linux warto ustawić przekierowanie do repozytorium FLINT.docker. - FLINT.docker: Obecna dokumentacja nie opisuje przeznaczenia tego repozytorium, które ma na celu udostępnianie FLINT FLINT za pomocą Dockera. Obsługa Dockera jest ograniczona do Ubuntu 18.04 (Bionic Beaver), ale można ją rozszerzyć na inne dystrybucje systemu Linux. W obecnej dokumentacji należy też położyć nacisk na sekwencyjny sposób konfigurowania plików dockerfiles, a także wystarczającą ilość informacji o sposobie tworzenia pliku na podstawie pliku Makefile. - FLINT.example: Obecna dokumentacja nie zawiera informacji o przeznaczeniu tego repozytorium, którym jest przykład użycia FLINT. Różne przykładowe uruchomienia można lepiej posegregować za pomocą konkretnych instrukcji. Musimy też połączyć to repozytorium z naszym głównym repozytorium FLINT, aby użytkownicy mogli się do niego poruszać i poznać przykład.
Do bieżącej dokumentacji należy dodać te informacje: – Korzystanie z Git i GitHuba: będą one zawierać szczegółowe instrukcje dotyczące tworzenia rozwidlenia, klonowania i konfigurowania zdalnego strumienia repozytorium. Znajdziesz w nim również informacje o tym, jak rekonstruować bazy danych na podstawie najnowszej wersji mastera i jak rozwiązywać konflikty scalania. – Plakietki i emotikony: w bieżącej dokumentacji brakuje plakietek i emotikonów, dzięki którym nowi współtwórcy poczują się mile widziani i ułatwią im rozwiązywanie problemów. – Informacje o problemach dla początkujących/użytkowników przystępnych dla początkujących: ułatwi to przekierowanie nowych użytkowników do problemów z łatwością dla początkujących i na stronie społeczności. – Informacje o repozytorium Import-me: repozytorium Import-me działa jako szablon bazowy do szybkiego uruchamiania repozytorium Moja Global. W bieżącej dokumentacji nie wspomina się o tym samym znaczeniu. Trzeba je zaktualizować, podając wzmiankę o repozytorium Import-me. Należy też dodać instrukcję wybierania tego repozytorium jako szablonu podczas tworzenia nowego repozytorium. Powinien też istnieć proces sugerowania dodatkowych funkcji dla repozytorium Import-me.
Etap 2. Utwórz centralne, samodzielne repozytorium dokumentacji
Narzędzie używane na potrzeby platformy hostingowej:
Narzędziami proponowanymi dla tej platformy hostingowej jest Czytaj dokumenty z następujących powodów: – Wysoka pozycja w rankingu na różnych platformach hostingowych. – Automatyczna aktualizacja przy przekazywaniu zatwierdzenia
Uporządkuj wszystkie treści w logiczny sposób sekwencyjny:
Proponowana kolejność treści jest następująca: – Wprowadzenie do dokumentacji dla deweloperów: ta sekcja zawiera wprowadzenie do Moja Global Global i FLINT. – Udział: ta sekcja zawiera podsekcje „Sposoby współtworzenia systemu Windows” (dotyczące kodu/zgłaszania błędów, tłumaczenia, dokumentacji/organizowania zdarzeń itp.) oraz „Kodeks postępowania”. – Konfiguracja podczas programowania: ta sekcja składa się z podsekcjach „Git & GitHub Workflow” i „Linux Instalacja i kolejna faza udokumentowania”. – Przepływ pracy programisty w ramach testowania i integracji narzędzi do testowania: ta sekcja obejmuje testy i sposoby przeprowadzania testów. – Dołącz do nas: w tej sekcji znajdziesz różne fora społecznościowe, takie jak kanały na Slacku, które ułatwią Ci nawiązanie kontaktu i współpracę z Moja Global.
Etap 3. Dodawanie przepływu pracy programisty i strony społeczności dla nowych współtwórców:
Dokumentacja przepływu pracy dla programistów:
Dokumentacja przepływu pracy dla programistów będzie się składała z tych podsekcji:
- Użyty stos technologiczny/architektura i różne moduły w kodzie: dokumentacja umożliwiająca zapoznanie nowych współtwórców z zaimplementowanym stosem technologicznym, różnymi bibliotekami i modułami bazy kodu.
- Zintegrowane narzędzia do testowania i zasięg: przedstawiamy nowych współtwórców narzędzi potoków CI/CD używanych do testowania, boty wykrywające i automatyczne kontrole jakości przeprowadzane na ich kodzie. Przedstawiciel przekazał im też wskazówki, do kogo należy się zwrócić w przypadku niepowodzenia testu.
- Boty ułatwiające pracę, np.Zulipbot: projektowanie szablonów treści dla botów i udostępnianie dokumentacji umożliwiającej użytkownikom zrozumienie botów, a nawet ulepszanie ich konfiguracji dzięki udziałowi w ich działaniu.
- Ręczne testowanie i przesyłanie żądań pull: wymagana dokumentacja ręcznego testowania żądań pull pod kątem określonych standardów oraz przesyłania wyników w postaci zrzutów ekranu lub GIF-ów podczas przesyłania żądań pull.
- Pobranie wskazówek dotyczących sprawdzania próśb, których muszą przestrzegać współtwórcy: wskazówki dotyczące oznaczania określonych zespołów do sprawdzenia i dodawania do prośby o weryfikację etykiety np. „Wymaga sprawdzenia”, aby osoby odpowiedzialne za obsługę mogły na nie odpowiadać.
Strona internetowa społeczności:
Strona internetowa społeczności będzie zawierać następujące funkcje:
- Informacje o naszym przepływie pracy: przepływ pracy będzie się składał z serii działań, od których może zacząć nowy współtwórca, np.zgłoszenia pierwszego problemu z licznikami czasu, potem zgłoszenia problemu z licznikami czasu dla innej osoby i pomocy innym przez przesłanie opinii i sprawdzenie ich żądań pull.
- Lista problemów związanych tylko z pierwszym licznikiem czasu: lista problemów przeznaczonych specjalnie dla nowych lub nowych użytkowników.
- Lista nieaktualnych problemów: lista problemów, nad którymi nie pracowano od dłuższego czasu, więc użytkownicy mogą je wybierać.
- Lista współtwórców: lista współtwórców, którzy do tej pory przekazali darowiznę w repozytoriach Moja Global.
- Ostatni współtwórcy: lista użytkowników, którzy niedawno przekazali darowiznę w repozytoriach 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 w celu odpowiadania na pytania i dyskutowania o projektach.