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
- Electron
- Specjalista ds. technicznych:
- Mister Gold
- Nazwa projektu:
- Samouczek dotyczący Electrona
- Długość projektu:
- Standardowa długość (3 miesiące)
Opis projektu
PODSUMOWANIE PROJEKTU
Electron to jedno z najpopularniejszych narzędzi do tworzenia wieloplatformowych aplikacji komputerowych za pomocą JavaScript, HTML i CSS. Kolekcja aplikacji opartych na Electron ma prawie 900 pozycji, a ta lista stale się wydłuża. Niektóre z najpopularniejszych narzędzi dla programistów, takie jak Visual Studio Code, Atom, Postman, Slack czy GitKraken, są tworzone na podstawie Electrona.
Popularność Electrona wynika z łatwego do nauczenia się kodu i niskiego progu wejścia – każdy, kto zna JavaScript, HTML i CSS, może tworzyć własne aplikacje. Duże ogólne wskaźniki wzrostu wymuszają tworzenie samouczków i instrukcji, które są łatwe do zrozumienia i użycia.
Celem projektu jest zwiększenie pewności siebie twórców aplikacji, którzy dopiero zaczynają korzystać z ramy Electron, oraz zapewnienie im spójnego i usprawnionego procesu tworzenia własnych aplikacji Electron od podstaw.
Problemy z projektem
Poniżej znajdziesz listę najważniejszych problemów związanych z dokumentacją samouczków Electrona: 1. Niejasne informacje wprowadzające i nieintuicyjne w obszarze tworzenia aplikacji. 2. Rozproszone i niepotrzebne informacje związane z procesem tworzenia aplikacji. 3. Nieuporządkowane fragmenty instrukcji z przewodnika „Pierwsze kroki” bez jednego wiarygodnego źródła informacji
PROPOZYCJA PROJEKTU
Zgodnie z celem projektu i wymienionymi powyżej problemami przedstawiamy listę proponowanych ulepszeń: 1. Zaktualizuj istniejące przewodniki. Aby ułatwić i ujednolicić pierwsze kroki, należy zaktualizować te dokumenty, stopniowo przechodząc od prostych do bardziej złożonych: - Środowisko dewelopera - Tworzenie pierwszej aplikacji Electron - Dodawanie funkcji do aplikacji (tworzenie strony podsumowania) - Pakowanie i rozpowszechnianie aplikacji 2. Zmień strukturę katalogu dokumentacji. Aby pokazać nowym deweloperom, co jest niezbędne na początku i co można uznać za kolejne kroki, strona z dokumentacją powinna zawierać zarówno wizualne, jak i kontekstowe podziały na etapy, które pozwolą jak najszybciej opublikować pierwszą aplikację. Restrukturyzacja obejmuje też wskazówki dotyczące możliwych dalszych kroków. 3. uporządkować i ujednolicić dokumentację dotyczącą tworzenia aplikacji; Wszystkie funkcje powinny mieć ujednolicony zestaw instrukcji dotyczących ich instalowania i włączania, szybkiego rozpoczęcia korzystania z aplikacji, pracy z aplikacją po jej pierwszym uruchomieniu oraz dystrybucji. 4. Dodaj repozytorium electron-api-demos do dokumentacji. Repozytorium electron-api-demos zawiera zestaw przykładów, które pokazują, jak dodawać funkcje do aplikacji Electron. Te informacje powinny być zawarte w przewodniku dotyczącym dodawania funkcji do aplikacji, aby zachować spójność z strategią dotyczącą pojedynczego źródła informacji. 5. Włącz przykłady Electron Fiddle do dokumentacji. Dzięki temu nowym deweloperom łatwiej będzie sprawdzić, jak działa dany fragment kodu, bez konieczności powtarzania tych czynności ręcznie. Integracja obejmuje napisanie przykładowego kodu do zaktualizowanych samouczków oraz dodanie przycisku „Uruchom w Fiddle” do bloków kodu.
Przebieg
Okres sprawdzania zgłoszenia – zapoznaj się ze społecznością i osobami, z którymi będziesz współpracować. Poznaj wskazówki i sprawdzone metody dotyczące tworzenia treści dla społeczności. Opublikuj pierwsze rzeczy. Nawiązywanie więzi ze społecznością – poznaj społeczność. Sprawdź aktualny stan dokumentacji Electron. Zidentyfikuj słabe punkty. Tydzień 1. Ustal z mentorami etapy projektu i wymagania. Tydzień 2. Przejrzyj strony dotyczące środowiska programisty i tworzenia pierwszej aplikacji Electron. Tydzień 3. Przejrzyj strony dotyczące architektury aplikacji, dodawania funkcji do aplikacji oraz pakowania i rozpowszechniania aplikacji. Utwórz stronę podsumowania z listą funkcji, które można dodać do aplikacji.Tydzień 4. Zmień strukturę katalogu dokumentacji.Tydzień 5. Przygotuj szablon integracji przykładów interfejsu Electron API z główną dokumentacją.Tygodnie 6–7. Przekształć repozytorium przykładów interfejsu Electron API.Tydzień 8. Przygotuj szablon integracji Electron Fiddle z główną dokumentacją. Napisz pierwszy przykład. Tygodnie 9–10: zintegruj Electron Fiddle z główną dokumentacją. Tygodnia 11: dokończ tworzenie głównej struktury dokumentacji i stron po przeniesieniu repozytorium electron-api-demos i próbek Electron Fiddle. Tygodnia 12: oceń wyniki.
SZCZEGÓŁOWY ZESTAWIENIE DANYCH WARUNKÓW
OKRES OCENY APLIKACJIPierwsza część tego okresu będzie poświęcona sprawdzaniu kanałów społeczności i kodu źródłowego oraz kontaktowaniu się z osobami zaangażowanymi w projekt.
Druga część tego okresu będzie poświęcona ogólnie kulturze tworzenia treści, omówieniu przewodników i sprawdzonych metod dotyczących tworzenia treści. Wtedy będziesz mieć możliwość dodawania pierwszych treści, aby sprawdzić, jak działa proces.
POWIĄZANIE SPOŁECZNOŚCI
Ten czas zostanie poświęcony na dokładniejsze zapoznanie się z folderem dokumentacji i jego harmonogramem. Na podstawie tych informacji będzie możliwe zidentyfikowanie słabych punktów (np. niekompletnych lub brakujących części), które można poprawić. Aby wypełnić luki, twórz (w miarę możliwości) prośby o przechwycenie.
TYDZIEŃ 1 – TYDZIEŃ 2
Pierwszy tydzień będzie przeznaczony na komunikację z mentorami, aby ustalić planowane etapy i termin realizacji zadań.
Drugi tydzień będzie poświęcony zapoznaniu się z informacjami na stronach Środowisko dewelopera i Tworzenie pierwszej aplikacji Electron. W przypadku strony Środowisko programisty będzie to obejmować redagowanie ogólnego omówienia i korektę. W przypadku strony Tworzenie pierwszej aplikacji Electron będzie to stworzenie spójnego przewodnika krok po kroku z jasnymi punktami początkowymi i końcowymi oraz usunięcie zbędących informacji (np. 2 podobnych bloków kodu w sekcji „Electron Development in a Nutshell” i „Trying this example”).
Wyniki: zaktualizowane, łatwe do zrozumienia przewodniki wprowadzające, które pomogą Ci szybko rozpocząć pracę z aplikacjami Electron.
TYDZIEŃ 3
W tym tygodniu zajmiemy się: 1. ulepszeniami strony Architektura aplikacji. Dodano m.in.: - nową wersję dotychczasowych informacji w sekcji Procesy główne i procesory renderujące, aby były prostsze i bardziej intuicyjne dla nowych czytelników; - wizualną reprezentację architektury, która pokazuje, jak procesy są ze sobą połączone, jak się komunikują i czym się różnią. Przykłady wizualizacji: 1, 2, 3 (niska jakość). 2. ujednolicenie informacji o wszystkich funkcjach, które możesz dodać do aplikacji Electron. Obejmuje to redagowanie przewodników w taki sposób, aby uzyskać ujednolicony zestaw instrukcji instalowania i włączenia funkcji wraz z przykładem jej działania. Dodatkowo zostanie utworzona nowa strona (podsumowanie) z wykazaniem wszystkich dostępnych funkcji. Ujednolicone instrukcje mogą wyglądać tak: - Omówienie - Przykład: - Przykładowy kod - Przykład wizualny (w miarę możliwości)
- uproszczenie strony Dystrybucja aplikacji. Obejmuje to: a. wyłączenie Pakietu aplikacji z Przewodnikiem dotyczącym dystrybucji aplikacji; b. podzielenie metod dystrybucji na automatyczne i ręczne. c. traktowanie elektronu jako przykładu automatycznej dystrybucji; d. użycie informacji o asar ze strony Pakiety aplikacji, opisanie kopiowania plików źródłowych i tworzenia archiwum asar jako przykładów ręcznej dystrybucji. #### TYDZIEŃ 4 W tym tygodniu zostanie poświęcona zmiana struktury katalogu dokumentacji. Usługa ta obejmuje:
1. Podział dotychczasowych przewodników na co najmniej 3 kategorie:a. Krótkie wprowadzenie b. Podstawy c. Kroki zaawansowane
Kategoria Quickstart będzie zawierać podstawowe samouczki (instalacja, konfiguracja, dystrybucja), które umożliwią nowicjuszom szybkie rozpoczęcie pracy od zera. Każdy przewodnik powinien zawierać linki do poprzedniego i następnego przewodnika z serii.
Może ona wyglądać tak: 1. Wymagania wstępne: Zainstaluj urządzenie Electron. 3. Tworzenie podstawowej aplikacji. 4. Pakowanie/dystrybucja aplikacji
Po przejściu przez sekcję Szybkie wprowadzenie użytkownik pozna podstawy działania aplikacji Electron i będzie mieć w pełni działającą, możliwą do rozpowszechniania aplikację Electron.
Kategoria Podstawy zawierać będzie przewodniki, które pomogą Ci pogłębić wiedzę o Electronie i rozszerzaniu aplikacji utworzonej w sekcjach Krótkie wprowadzenie. Te przewodniki obejmują: - architekturę aplikacji, - dodawanie funkcji do aplikacji, - szablony i interfejsy wiersza poleceń.
Kategoria Zaawansowane kroki będzie zawierać bardziej zaawansowane przewodniki, które pomogą Ci skonfigurować i dostosować aplikację Electron: - Testowanie i debugowanie - Dostępność - Bezpieczeństwo - Aktualizacje
2 – Zmniejszenie liczby stron z dokumentacją. Obecna wersja dokumentacji zawiera pewne nakładające się treści i nieskategoryzowane instrukcje. Na przykład: - Instalacja i instalowanie Electrona w ramach tworzenia pierwszej aplikacji - Pakowanie aplikacji i pakowanie aplikacji do pliku w ramach dystrybucji aplikacji - Instrukcje nieskategoryzowane w kategoriach Szczegóły i Zaawansowane: Sugestia: przenieś te dokumenty na GitHub i wyklucz je z głównej dokumentacji. Te dokumenty są specyficzne dla wytycznych dotyczących tworzenia Electrona. Najpierw należy ich szukać w repozytorium kodu źródłowego: - Opracowywanie Electrona - Opracowywanie Chromium - Opracowywanie V8 - Problemy w Electronie - Poprawki w Electronie - Prośby o przejęcie - Struktura katalogu kodu źródłowego - Testowanie - Styl kodowania
Głównym celem zmniejszenia liczby dokumentów jest pozbycie się przytłaczającej liczby dostępnych przewodników, połączenie rozproszonych informacji w jedną całość i zapewnienie nowym użytkownikom bardziej ustrukturyzowanej, łatwej w nawigacji i przyjaznej dla użytkownika wersji dokumentacji Electron.
TYGODNIE 5–7
Tydzień 5 poświęcimy na przygotowanie szablonu (sposób), w jaki zaprezentujemy komponenty elektrona api-demos z główną dokumentacją. Ten szablon może wyglądać tak: 1. W głównej dokumentacji w sekcji „Dodawanie funkcji do aplikacji” utwórz kategorie reprezentowane w demo interfejsu electron-api. 2. Przechodząc przez poszczególne kategorie, przenieś przykłady demonstracyjne do głównej dokumentacji: - przykłady kodu można wziąć z kodu źródłowego lub z opisu odpowiedniej funkcji w aplikacji - każdy przeniesiony przykład powinien być powiązany z odpowiednim opisem - każdy przykład podrzędny (np. okno dialogowe z błędem jako element podrzędny okna dialogowego Użyj systemu) powinien być przeniesiony pod element nadrzędny
UWAGA 1. Przykłady znajdują się zarówno w demo dla interfejsu electron-api, jak i w głównej dokumentacji (np. skróty klawiszowe, przeciąganie i upuszczanie). W takim przypadku przykład z Elecron-api-demos powinien mieć priorytet, a przykład w głównej dokumentacji powinien zostać zignorowany.
UWAGA 2. Wiele przykładów w aplikacji electron-api-demos zawiera podgląd na żywo opisywanej funkcji. Ta funkcja będzie ignorowana do czasu integracji Electron Fiddle w tygodniach 9–10.
- Zaktualizuj stronę z listą wszystkich dostępnych funkcji (która została utworzona w tygodniu 3) z uwzględnieniem nowej hierarchii przykładów.
Tygodnie 6 i 7 będą poświęcone przeniesieniu przykładów z electron-api-demos do głównej dokumentacji zgodnie z omówionym powyżej szablonem. Na ostatnim etapie należy usunąć lub wycofać repozytorium electron-api-demos.
TYGODNIE 8–10
Tydzień 8 będzie poświęcony przygotowaniu szablonu (sposobu) integracji Electron Fiddle z główną dokumentacją. Ta inicjatywa została już uruchomiona (szczegóły znajdziesz w problemie #20442) przez zespół Electrona i wolontariuszy z społeczności, ale wymaga dopracowania.
Aby można było korzystać z próbek Fiddle, podstawowy szablon może wyglądać tak: 1. Wybierz przykład z głównej dokumentacji (na przykład krótkie wprowadzenie). W tym momencie dokumentacja powinna zawierać też przykłady z electron-api-demos. 2. Odtwórz przykład w Electron Fiddle (jako punktu wyjścia użyj przykładowego kodu lub kodu źródłowego); 3. Zapisz Fiddle lokalnie w folderze; 4. Przenieś przykład do katalogu /docs/fiddles/[CATEGORY]/[SECTION]/[DEMO]. * Listę ukończonych przykładów znajdziesz w sekcji „Lista wersji demonstracyjnych” tego problemu. 5. Dodaj przycisk „Uruchom w Fiddle” zgodnie z opisem w pierwszym komentarzu do problemu #2848.
Tydzień 9 i 10 będzie poświęcony na zintegrowanie przykładów demonstracyjnych elektronów (które zostały już przekonwertowane na skrzypce) z główną dokumentacją zgodnie z szablonem opisanym powyżej.
TYDZIEŃ 11
Ten tydzień zostanie w pełni przeznaczony na finalizację projektu pisania po udanej migracji repozytorium electron-api-demos i przykładów skrzypiec Electron. Dotyczy to: - sprawdzenia, czy wszystkie istniejące przykłady kodu mają przycisk „Uruchom w Fiddle”; - sprawdzenia, czy wszystkie istniejące przykłady kodu działają prawidłowo jako Fiddle; - sprawdzenia, czy główna dokumentacja nie odwołuje się już do repozytorium electron-api-demos.
TYDZIEŃ 12
Kończenie pracy. Sprawdzanie akceptacji.