Ta strona zawiera szczegółowe informacje na temat projektu technicznego przyjęta do programu Sezon Dokumentów Google.
Podsumowanie projektu
- Organizacja open source:
- Elektronowy
- Pisarz techniczny:
- Mistrz Złoty
- Nazwa projektu:
- Elektron – samouczek
- 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 w języku JavaScript, HTML i CSS. Kolekcja aplikacji utworzonych na bazie Electron zawiera prawie 900 pozycji i stale się powiększa. Niektóre z najpopularniejszych narzędzi dla programistów, takie jak Visual Studio Code, Atom, Postman, Slack i GitKraken, są tworzone na platformie Electron.
Popularność Electron wynika z prostej krzywej uczenia się i niskiego progu wejścia. Każdy, kto zna język JavaScript, HTML, stos CSS, może stworzyć własną aplikację. Ogromne ogólne tempo wzrostu jest konieczne do tworzenia samouczków i przewodników dla początkujących, które są łatwe w obsłudze.
Celem tego projektu jest przekonanie twórców aplikacji, którzy dopiero zaczynają korzystać z platformy Electron, oraz zapewnienie im spójnego i prostego sposobu tworzenia własnych aplikacji Electron od podstaw.
Problemy związane z projektem
Oto lista najważniejszych problemów związanych z dokumentacją samouczków Electron: 1. Niejasne przedstawienie punktu początkowego i nieintuicyjne wprowadzenie na temat kroków tworzenia aplikacji. 2. rozproszone i zbędne informacje związane z procesem tworzenia aplikacji. 3. Nieuporządkowane fragmenty instrukcji dla początkujących, bez jednego źródła wiarygodnych informacji
PROPOZYCJA PROJEKTU
Oto lista proponowanych ulepszeń, wiążąca się z celem projektu i problemami opisanymi powyżej: 1. Zaktualizuj istniejące przewodniki. Aby wykonanie pierwszych kroków było płynne i spójne, stopniowo przechodź z prostych do bardziej złożonych dokumentów: – środowisko dewelopera, – pisanie pierwszej aplikacji Electron, – dodawanie funkcji do aplikacji (utwórz stronę podsumowania). – pakowanie i dystrybucja aplikacji. 2. Zmień strukturę katalogu dokumentacji. Aby pokazać nowym programistom, co jest niezbędne do rozpoczęcia pracy, a co można uznać za kolejne kroki, strona z dokumentami powinna zawierać zarówno wizualny, jak i kontekstowy podział czynności, dzięki którym jak najszybciej można wdrożyć pierwszą aplikację. Przekształcenie obejmuje też wskazówki dotyczące kolejnych kroków. 3. Uporządkowanie i ujednolicenie dokumentacji tworzenia aplikacji. Wszystkie funkcje powinny zawierać ujednolicony zestaw instrukcji instalacji lub włączania aplikacji, szybkiego rozpoczęcia pracy z aplikacją po jej pierwszym opublikowaniu i rozpowszechniania jej. 4. Dołącz do dokumentacji repozytorium electron-api-demos. Repozytorium electron-api-demos zawiera zestaw przykładów pokazujących, jak dodawać funkcje do aplikacji Electron. Te informacje należy uwzględnić w przewodniku po dodawaniu funkcji do aplikacji, aby zachować spójność ze strategią dotyczącą treści opartych na jednym źródle wiarygodnych treści. 5. Zintegruj przykłady Electron Fiddle z dokumentacją. Ułatwi to nowym programistom sprawdzenie, jak działa dany fragment kodu bez konieczności powtarzania tych czynności ręcznie. Integracja obejmuje pisanie przykładowych kodów zaktualizowanych samouczków i dodawanie przycisku „Uruchom w Fiddle” do bloków kodu.
Przebieg
Okres sprawdzania zgłoszeń – zapoznaj się ze społecznością i osobami, z którymi chcesz współpracować. Poznaj przewodniki i sprawdzone metody dotyczące wkładu społeczności. Opublikuj pierwsze wpisy. Więź ze społecznością – poznaj społeczność. Sprawdź bieżący stan dokumentacji Electron. Wskaż słabe punkty. Tydzień 1 – omówienie kroków milowych i elementów projektu z udziałem mentorów Tydzień 2 – zmiany środowiska programistycznego i pisanie pierwszej strony aplikacji Electron Tydzień 3 – poprawa architektury aplikacji, dodawanie funkcji do aplikacji, pakiety aplikacji i strony dystrybucji. Tworzenie strony podsumowania z listą funkcji, które można dodać do aplikacji Tydzień 4 – zmiana struktury katalogu dokumentacji Tydzień 5 – przygotowanie szablonu informującego o tym, jak funkcja electron-api-demos zostanie zintegrowana z główną dokumentacją Tygodnie 6–7 – Migracja repozytorium electron-api-demos Tydzień 8 – Przygotuj szablon przedstawiający sposób zintegrowania dokumentacji Electron z Fid Napisz pierwszą próbkę. Tydzień 9–10 – integracja Electron Fiddle z główną dokumentacją Tydzień 11 – finalizacja głównej struktury dokumentacji i stron po migracji repozytorium electron-api-demos i próbek Electron Fiddle Tydzień 12 – ocena wyników
SZCZEGÓŁOWY ROZDZIAŁ SKŁADÓW MILOWYCH
CZAS SPRAWDZANIA APLIKACJI Pierwsza część okresu będzie poświęcona sprawdzaniu kanałów społeczności i kodu źródłowego oraz kontaktowania się z osobami zaangażowanymi w projekt.
W drugiej części szkolenia omówimy ogólnie kulturę twórczą i sprawdzone metody publikowania treści. To będzie czas na pierwsze posty, aby przekonać się, jak działa proces.
SPOŁECZNOŚĆ SPOŁECZNOŚCI
Poświęcimy ten czas na dogłębne przyjrzenie się folderowi z dokumentacją wraz z planem rozwoju. Na podstawie tych informacji można zidentyfikować słabe punkty (np. niekompletne lub brakujące elementy), które można poprawić. W miarę możliwości utwórz żądania pull, aby uzupełnić luki.
TYDZIEŃ 1 – TYDZIEŃ 2
Pierwszy tydzień będzie poświęcony komunikowaniu się z mentorami, aby pomóc Ci w osiągnięciu oczekiwanych kroków milowych i terminowym realizacji zadań.
W drugim tygodniu skupimy się na redagowaniu środowiska programistycznego i tworzeniu stron swojej pierwszej aplikacji Electron. W przypadku strony Środowisko dla deweloperów będzie to wymagać przeredagowania ogólnego omówienia i korekty. W przypadku strony Write Your First Electron App (Napisz swoją pierwszą aplikację Electron) należy umieścić na niej spójny szczegółowy przewodnik z jasnym punktem początkowym i końcowym oraz usunąć zbędne informacje (takie jak dwa podobne bloki kodu w sekcji Electron Development w Nutshell i Wypróbuj ten przykład).
Dostarczane treści: poprawione, przystępne przewodniki wprowadzające dotyczące sposobów szybkiego rozpoczęcia pracy z aplikacjami Electron.
TYDZIEŃ 3
W tym tygodniu skupimy się na: 1. ulepszeniach strony Architektura aplikacji, Obejmuje to: – przeredagowanie dotychczasowych informacji w sekcjach Główny i proces renderowania tak, aby były proste i intuicyjne dla początkujących, – dodanie wizualnej reprezentacji architektury, sposobu łączenia procesów, sposobu komunikacji i ich podstawowych różnic. Przykłady treści wizualnych: 1, 2, 3 (niska jakość). 2. Ujednolicenie informacji o wszystkich funkcjach, które można dodać do aplikacji Electron. Obejmuje to przeredagowanie instrukcji w celu uzyskania ujednoliconego zestawu instrukcji instalowania lub włączania funkcji wraz z przykładem jej działania. Zostanie też utworzona nowa strona (podsumowanie) z listą wszystkich dostępnych funkcji. Ujednolicone instrukcje mogą wyglądać tak: - Omówienie - Przykład: - przykładowy kod - Przykładowy kod (jeśli to możliwe)
- uproszczenia strony Rozpowszechnianie aplikacji. Obejmuje to: a. łączenie pakietów aplikacji z przewodnikiem po dystrybucji aplikacji; b. podział metod dystrybucji na automatyczną i ręczną; c. wykorzystanie kuźni elektronów jako przykładu automatycznej dystrybucji; d. wybranie informacji o asar ze strony Pakowanie aplikacji i opisanie kopiowania plików źródłowych i tworzenia archiwum asar jako przykładów dystrybucji ręcznej. #### TYDZIEŃ 4 Ten tydzień będzie poświęcony restrukturyzacji katalogu dokumentacji. Znajdziesz w nich m.in. te informacje:
1 – dzielenie istniejących przewodników na co najmniej 3 kategorie: a. Krótkie wprowadzenie b. Podstawy c. Czynności zaawansowane
Kategoria Krótkie wprowadzenie zawiera podstawowe samouczki (instalacja, konfiguracja, dystrybucja) tworzące spójną serię przewodników, które pozwolą początkującym szybko rozpocząć pracę od zera. Każdy przewodnik powinien zawierać linki do poprzednich lub następnych przewodników z tej serii.
Może ona wyglądać tak: 1. Wymagania wstępne 2. Zainstaluj Electron. 3. Utwórz podstawową aplikację. 4. Pakowanie i rozpowszechnianie aplikacji
Po ukończeniu sekcji Krótkie wprowadzenie użytkownik zna podstawy działania aplikacji Electron i otrzymuje w pełni działającą aplikację Electron, którą można dystrybuować.
Kategoria „Nauka podstaw” zawiera przewodniki, których celem jest pogłębienie wiedzy na temat Electron i rozszerzenie aplikacji utworzonej w sekcjach Krótkie wprowadzenie. Przewodniki te obejmują: – architekturę aplikacji, – dodawanie funkcji do aplikacji, – schematy i interfejsy wiersza poleceń.
Kategoria Kroki zaawansowane zawiera bardziej zaawansowane przewodniki dotyczące konfigurowania i dostrajania aplikacji Electron: - testowanie i debugowanie - Ułatwienia dostępu - Zabezpieczenia - Aktualizacje
2 – zmniejszenie liczby stron z dokumentacją. Obecna wersja dokumentacji zawiera treści pokrywające się w pewnym stopniu i instrukcje bez kategorii. Na przykład: – Instalacja i instalowanie Electron w ramach pisania pierwszej aplikacji; – Pakowanie aplikacji i pakowanie aplikacji do pliku w ramach dystrybucji aplikacji; – Instrukcje bez kategorii w kategoriach Szczegóły i Zaawansowane: Sugestia: przenieś następujące dokumenty do GitHuba i wyklucz je z głównej dokumentacji. Te dokumenty mają związek ze wskazówkami dotyczącymi tworzenia Electron, a najważniejsze, gdzie szukać ich znajdziesz w repozytorium źródłowym: - Programowanie Electron - Programowanie Chromium - Programowanie V8 - Problemy w Electron - łatki w Electron - Żądania pull - Struktura katalogu kodu źródłowego - testowanie - Styl kodowania
Główną ideą redukcji jest pozbycie się przytłaczającej liczby dostępnych przewodników, łączenie rozproszonych fragmentów informacji i udostępnienie nowej dokumentacji bardziej uporządkowanej, łatwiejszej w nawigacji i przyjaznej dla użytkownika wersji dokumentacji Electron.
TYGODNIE 5–7
Piąty tydzień będzie poświęcony opracowaniu szablonu (sposobu) integracji usługi electron-api-demos z główną dokumentacją. Szablon może wyglądać tak: 1. W głównej dokumentacji, w sekcji „Dodawanie funkcji do aplikacji”, utwórz kategorie zawarte w prezentacji electron-api-demos. 2. Przechodząc przez każdą z kategorii, przenieś przykłady demonstracyjne do głównej dokumentacji: – Przykłady kodu można pobrać z kodu źródłowego lub z opisu odpowiedniej funkcji w aplikacji. – Każdemu przeniesionemu przykładowi należy dodać powiązany opis. – Każdy przykład podrzędny (np. okno dialogowe Błąd jako element podrzędny okna dialogowego Korzystanie z systemu należy przenieść do elementu nadrzędnego).
UWAGA 1: istnieją przykłady, które występują zarówno w wersji demonstracyjnej electron-api-demos, jak i w głównej dokumentacji (np. skróty klawiszowe, przeciąganie i upuszczanie). W tym przypadku priorytet z demonstracji electron-api-demos powinien być inny, a przykład z głównej dokumentacji należy zignorować.
UWAGA nr 2: wiele przykładów w aplikacji electron-api-demos zawiera wersję demonstracyjną na żywo omawianej funkcji. Ta funkcja będzie ignorowana do czasu integracji z Electron Fiddle w tygodniach: 9–10.
- Zaktualizuj stronę z listą wszystkich dostępnych funkcji (utworzonych w tygodniu 3) z uwzględnieniem nowej hierarchii przykładów.
Tydzień 6 i 7 będzie poświęcony przenoszeniu przykładów demonstracji electron-api-demos do głównej dokumentacji zgodnie z opisem powyżej. Na koniec należy usunąć lub wycofać repozytorium electron-api-demos.
TYGODNIE 8–10
W ósmym tygodniu omówimy przygotowanie szablonu (czyli sposobu) integracji aplikacji Electron Fiddle z główną dokumentacją. Inicjatywa ta została już zainicjowana (szczegóły znajdziesz w numerze nr 20442) przez członków zespołu Electron wraz z wolontariuszami ze społeczności, ale wymaga ona odpowiedniego sfinalizowania.
Aby można było kontynuować próbkowanie aplikacji Fiddle, podstawowy szablon może wyglądać tak: 1. Wybierz przykład z głównej dokumentacji (np. krótkiego wprowadzenia). Na tym etapie dokumentacja powinna też zawierać przykłady electron-api-demos. 2. Utwórz ponownie przykład w Electron Fiddle (jako punkt 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/[KATEGORIA]/[SECTION]/[DEMO]. * Lista ukończonych przykładów jest opisana w sekcji „Lista wersji demonstracyjnych” danego problemu. 5. Dodaj przycisk „Uruchom za pomocą Fiddle” zgodnie z opisem we wstępnym komentarzu w numerze problemu nr 2848.
Tygodnie 9 i 10 będzie poświęcona integrowaniu przykładów demonstracyjnych funkcji electron-api-demos (które zostały już przekształcone w wersje Fiddlesa) z główną dokumentacją zgodnie z opisem powyżej.
TYDZIEŃ 11
W tym tygodniu skupimy się na finalizacji projektu pisania po migracji repozytorium electron-api-demos i próbek Electron Fiddle. Obejmuje to: - sprawdzenie, czy we wszystkich istniejących przykładach kodu znajduje się przycisk „Uruchom w Fiddle”, - sprawdzenie, czy wszystkie istniejące przykłady kodu działają prawidłowo jako Fiddles, - sprawdzenie, czy główna dokumentacja nie odnosi się już do repozytorium electron-api-demos.
TYDZIEŃ 12
Finalizowanie ukończonych prac. Kontrole akceptacji.