Ta strona została przetłumaczona przez Cloud Translation API.

moja globalny projekt

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:: moja globalna
Pisarz techniczny:: Tlazypanda
Nazwa projektu:: Dokumentacja technicznego przewodnika wprowadzającego do FLINT
Długość projektu:: Standardowa długość (3 miesiące)

Opis projektu

Dokumentacja technicznego przewodnika wprowadzającego dla FLINT, która pomoże nowym współtwórcom przeprowadzić wprowadzenie technicznego, tak aby nowi współtwórcy mogli łatwo rozpocząć pracę z minimalnym wsparciem zespołu pomocy.

Problemy związane z projektem

Oto lista najważniejszych problemów związanych z bieżącą dokumentacją: – Nieuporządkowane fragmenty instrukcji konfiguracji lokalnego przewodnika po konfiguracji utrudniające rozpoczęcie pracy nowemu uczestnikowi. – W wielu repozytoriach FLINT nie ma dokumentacji dotyczącej ich przeznaczenia i nie są ze sobą powiązane, co utrudnia nowemu użytkownikowi określenie, które repozytorium ma zostać zainstalowane. - Instalacja w systemie Windows jest dobrze udokumentowana, ale w dokumentacji instalacji systemu Linux można poprawić. - Przepływ pracy Git nie jest obecnie częścią dokumentacji

Proponowane rozwiązanie

Ta propozycja stanowi rozwiązanie, które pozwoli nowym współtwórcom przeprowadzić wprowadzenie technicznego, tak aby nowi aktywni użytkownicy mogli łatwo rozpocząć pracę z minimalnym wsparciem ze strony opiekunów. Można to osiągnąć przez refaktoryzację bieżącej dokumentacji, aby była zrozumiała dla początkujących. Dodatkowo można utworzyć centralne, samodzielne repozytorium na wszystkie dostępne dokumenty. Projekt jest podzielony na 3 fazy: – Przegląd istniejącej dokumentacji i refaktoryzacja. Celem tego etapu jest przejrzenie bieżącego przewodnika i refaktoryzacja go w taki sposób, aby był zwięzły i zrozumiały dla nowych uczestników. Należy też zmodyfikować dokumentację, aby była bardziej przystępna dla początkujących przez dodanie plakietek, emotikonów i informacji o problemach oznaczonych jako przeznaczone tylko dla osób po raz pierwszy lub te, które są prawidłowe w pierwszej kolejności. – Utwórz centralne, samodzielne repozytorium dokumentacji: celem tego etapu jest połączenie w logicznej kolejności całej dokumentacji z samodzielnym repozytorium. Polega to na ustaleniu wytycznych dotyczących udostępniania, 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 wskazówki dotyczące git contribution, architekturę techniczną projektu oraz wskazówki dotyczące testowania i kontroli jakości. Proponowana witryna społeczności będzie aplikacją jednostronicową wyświetlającą informacje o przepływie pracy i problemach po raz pierwszy, które mogą zgłosić nowi współtwórcy oraz listę wszystkich współtwórców. Etap 1. Przejrzyj istniejącą dokumentację i refaktoryzację

Zmodyfikuj obecną dokumentację tych repozytoriów: – FLINT: bieżąca dokumentacja nie jest zbyt szczegółowa i nie zawiera sekwencyjnej kolejności wymaganych bibliotek wstępnych. Szczegółowe instrukcje są podzielone na różne pliki PDF, ale możesz je wyświetlić w jednym miejscu w bardziej zwięzły sposób. Przewodniki instalacji dotyczą też systemu Windows, ale w przypadku instalacji systemu Linux korzystne może być przekierowanie instalacji do systemu Linux do repozytorium FLINT.docker. - FLINT.docker: Obecna dokumentacja nie opisuje przeznaczenia tego repozytorium, które służy do udostępniania instalacji FLINT na Linuksie za pomocą Dockera. Obsługa Dockera jest ograniczona tylko do Ubuntu 18.04 (Bionic Beaver), ale można ją rozszerzyć na inne dystrybucje systemu Linux. W obecnej dokumentacji należy również położyć nacisk na sekwencyjny sposób konfigurowania plików dockerfiles, a także wystarczającą ilość informacji o tym, jak tworzyć pliki z pliku Makefile. - FLINT.example: Obecna dokumentacja nie wskazuje przeznaczenia tego repozytorium, które jest przykładem użycia FLINT. Różne przykładowe uruchomienia można lepiej rozdzielić za pomocą konkretnych instrukcji. Musimy też połączyć to repozytorium z naszym głównym repozytorium FLINT, aby użytkownicy mogli się tu poruszać i zobaczyć przykład w praktyce.

Do bieżącej dokumentacji należy dodać te informacje: – Zastosowanie Git i GitHub: szczegółowe instrukcje dotyczące tworzenia rozwidlenia, klonowania i ustawiania zdalnego strumienia repozytorium dla repozytorium. Znajdziesz w nim też informacje o tym, jak przeprowadzić migrację względem najnowszej instancji głównej i jak rozwiązywać konflikty scalania. – Plakietki i emotikony: w bieżącej dokumentacji nie ma plakietek ani emotikonów, dzięki którym nowi współtwórcy czuli się mile widziani i mogli łatwiej odnaleźć problem. - Informacje o problemach dla początkujących/początkujących: ułatwi to przekierowanie nowych współtwórców do problemów przystępnych dla początkujących oraz do witryny społeczności. - Informacje o repozytorium Import-me: repozytorium Import-me jest szablonem bazowym do szybkiego uruchamiania repozytoriów Moja Global. W bieżącej dokumentacji nie ma wzmianki o tym samym znaczeniu. Trzeba je zaktualizować, aby uwzględnić repozytorium Import-me. Musisz też dodać instrukcje wybierania go jako szablonu podczas tworzenia nowego repozytorium. Powinien też zostać opracowany proces sugerowania dodatkowych funkcji repozytorium Import-me.

Etap 2. Utwórz centralne, samodzielne repozytorium dokumentacji

Narzędzie używane do hostingu platformy:

Narzędziami proponowanymi dla tej platformy hostingowej jest dokument Read The Dokumenty z następujących powodów: – Umiejscowienie wysoko wśród różnych platform hostingowych. – Automatyczna aktualizacja w trakcie przekazywania zatwierdzenia – Łatwa konfiguracja i pomoc w rozwiązywaniu problemów jest dostępna dzięki dużej społeczności. – Dokumentacja jest sformatowana przy użyciu reStructuredText, a wyniki są kompilowane przez Sphinxa.

Uporządkuj wszystkie treści w logiczny sposób sekwencyjny:

Proponowana kolejność materiałów jest następująca: – Wprowadzenie do dokumentacji dla programistów: ta sekcja zawiera wprowadzenie do oprogramowania Moja Global i FLINT. – Udział: ta sekcja składa się z podsekcji „Sposoby współtworzenia systemu Windows”, „Zgłaszanie błędów w kodzie, zgłaszanie błędów, tłumaczenie, dokumentacja, organizowanie zdarzeń itp.) oraz „Kodeks postępowania”. – Konfiguracja programowania: ta sekcja składa się z podsekcji „Instalacja systemu Windows i przepływ pracy w systemie Windows”. – Kolejny etap procesu tworzenia dokumentacji dotyczący testowania i integracji narzędzi. – 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. Dodaj przepływ pracy programisty i stronę społeczności dla nowych współtwórców

Dokumentacja przepływu pracy programisty:

Dokumentacja przepływu pracy dla programistów będzie składała się z tych podsekcji:

Użyty stos technologiczny/architektura oraz 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 potoku CI/CD używanych do testowania, botów rejestrujących informacje i automatycznych kontroli jakości przeprowadzanych na podstawie ich kodu. Przekażemy też wytyczne, z kim należy się skontaktować w przypadku niepowodzenia testów.
Boty ułatwiające pracę, np.Zulipbot: projektowanie szablonów treści do wyświetlania botów i udostępnianie dokumentacji, która pozwoli użytkownikom lepiej zrozumieć działanie botów, a nawet ulepszyć konfigurację bota.
Ręczne testowanie i przesyłanie żądań pull: dostępna dokumentacja z informacjami o ręcznym testowaniu żądań pull pod kątem określonych standardów oraz wyników przesyłania w postaci zrzutów ekranu lub GIF-ów po przesłaniu żądań pull.
Pobierz wskazówki dotyczące weryfikacji próśb, których będą przestrzegać współtwórcy: wytyczne dotyczące oznaczania wybranych zespołów do sprawdzenia i dodawania do żądania pull etykiet takich jak „wymaga sprawdzenia”, aby właściciele usług mogli na nie odpowiadać.

Strona internetowa społeczności:

Witryna społeczności będzie miała następujące funkcje:

Informacje o naszym przepływie pracy: przepływ pracy składa się z serii działań, od których może zacząć nowy współtwórca, np.zgłoszenie problemu pierwszego licznika czasu, a następnie zgłoszenie problemu z licznikami czasu dla innej osoby i udzielenie pomocy innym przez przesłanie opinii i sprawdzenie ich żądań pull.
Lista problemów dotyczących tylko funkcji Pierwsze kroki: lista problemów przeznaczonych dla początkujących i nowych współtwórców.
Lista nieaktualnych problemów: lista problemów, nad którymi nie pracowano od dłuższego czasu, dlatego użytkownicy mogą je wybierać.
Lista współtwórców: lista użytkownikó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 rozwiązania problemów i dyskusji na temat projektów.