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
- Ekosystem ARK
- Pisarz techniczny:
- yslcrypto
- Nazwa projektu:
- Projekt 1. Wprowadzenie do tworzenia aplikacji blockchainowych
- Długość projektu:
- Standardowa długość (3 miesiące)
Opis projektu
Oto kilka uwag po przeczytaniu sekcji „Rozpoczęcie korzystania z usługi”:
JAK SKONFIGUROWAĆ ŚRODOWISKO PROGRAMISTY
Instalacja: Sprawdziłbym szczegółowo, jak zainstalować narzędzia dla programistów. Chciałbym udostępnić przykłady kodu wraz z typowymi błędami i sposobami ich naprawiania (możemy tutaj umieścić link do strony z instrukcjami rozwiązywania problemów).
Uruchomienie pierwszej sieci testowej: Pierwsze wrażenie: w tej chwili jest to dość mylące dla osób, które tylko przeglądają i chcą szybko skonfigurować sieć. Oto kilka rzeczy, które chciałbym zmienić:
Rozważ zdefiniowanie nawet podstawowych pojęć, takich jak testnet.
Dodaj więcej krótszych przykładów kodu: mkdir, cd itp. Możesz też je pogrupować, aby czytelnicy mogli łatwiej kopiować i wklejać. Nic nie jest zbyt proste, a wszyscy lubią kopiować i wklejać.
Po pierwszym przeczytaniu nie rozumiem, do czego służą kroki 1 i 2 w podsekcji dotyczącej uruchamiania przez sieć. Klikanie i przechodzenie przez linki wymaga zbyt wiele zastanowienia. Myślę, że możemy to znacznie uściślić, nie wdając się zbytnio w chaos.
W kroku 5 (który jest w rzeczywistości krokiem 4?) warto przynajmniej ogólnie omówić kontener podstawowy, aby czytelnik wiedział, co robi, bez klikania linku.
W przypadku kroków 3 i 5 (w istocie 4) wyjaśnię dłuższe przykłady kodu.
Na koniec podam link do zainstalowanej wtyczki i pliku, aby ułatwić życie czytelnikom.
Na koniec zmodyfikuję tak, aby w każdym akapicie było tylko jeden pomysł (umożliwia to łatwe przeglądanie). Warto też nadać tekstowi nieco weselszy i przyjaźniejszy ton oraz dodać kilka emotikonów.
JAK MONITOROWAĆ BLOCKCHAIN
Uprość pierwszy akapit. Wyjaśniłbym, czym jest wtyczka, co robi delegowanie (lub przynajmniej podałbym link do wyjaśnienia na podstawie podstawowych zasad), co oznacza fałszowanie bloku i podałbym przykład zdarzenia sieciowego.
Określ problem: Możesz dać czytelnikowi pojęcie o tym, czym jest pełny węzeł, podać link do bardziej szczegółowego wyjaśnienia i lepiej wyjaśnić kompromisy między pełnym węzłem a aplikacją zewnętrzną. Na koniec podam link do poprzedniej strony wprowadzającej, na której znajdują się informacje o konfigurowaniu działającego środowiska testowego i programistycznego, na końcu tej podsekcji (jeśli czytelnik natknął się na tę stronę po raz pierwszy).
Interfejs Events API: z listy dostępnych zdarzeń nie wynika, że do osiągnięcia zamierzonego celu powinniśmy użyć zdarzenia „block.applied”. Chociaż z podpowiedzi poniżej można się tego dowiedzieć, wyjaśnię to najpierw.
Nie rozumiem, co zwraca funkcja „block.applied”. Uważam, że ważne jest, aby to jasno określić.
W przykładowym kodzie na końcu warto wyraźnie zaznaczyć, że „block.generatorPublicKey” zastępuje „block.forger” (w poprzednim przykładzie pseudokodu), a „delegateKey” zastępuje „delegateWeAreMonitoring”. Aby zapewnić spójność przykładów kodu i pseudokodu, w instrukcji warunkowej zamieniłbym też „delegateKey” na „generatorKey”.
Tworzenie wtyczki: Chcę wyjaśnić, co w tym kontekście oznacza szkielet. Na przykład: Podobnie jak prawdziwe rusztowania na placu budowy, w tym kontekście rusztowanie oznacza prostą, wstępnie utworzoną strukturę dla Twojego plugina, na której możesz zbudować prawdziwą.
Dodam przykłady kodu służące do zmiany nazwy katalogu i wtyczki, pokażę przykładowy plik package.json i wyjaśnię, co oznacza „dodanie niezbędnej konfiguracji” do pliku plugin.js.
Połączenie: Chciałbym, aby zmiany były bardziej czytelne. Na koniec pochwal adresata i dołącz kilka emotikonów :)
JAK WYSŁAĆ PIERWSZĄ TRANSAKCJĘ ZA POMOCĄ PAKIETU ARK SDK
Pierwsze kroki: Dodałbym przykładowy kod, który pozwoli użytkownikowi utworzyć nowy katalog za pomocą kopiowania i wklejania.
Połączenie z Testnetem: Wyjaśnię, czym jest interfejs API REST (lub przynajmniej podam link do wyjaśnienia). Podaję link do przykładowego narzędzia do wyświetlania danych w formacie JSON. W drugiej wskazówce (ponieważ prosimy czytelnika o zrobienie czegoś) warto użyć przyjaźniejszego tonu.
Zmiana Menedżera konfiguracji: omówię typowe przykłady błędów związanych z siecią i zaproponuję link do sekcji dotyczącej rozwiązywania problemów.
Konfigurowanie kont nadających i odbierających: Dodałbym przykładowy kod, aby umożliwić czytelnikowi zmianę katalogu konfiguracji za pomocą kopiowania i wklejania. Dodaję przykładowy kod pokazujący zawartość pliku delegates.json.
JAK WYSYŁAĆ TRANSAKCJE ZA POMOCĄ INTERFEJSU ARK CORE TESTER CLI
Wymagania wstępne: Dodaję przykładowy kod, który pokazuje, jak pobrać działającą kopię repozytorium GitHub ARK Core, oraz inny, który przenosi czytelnika do odpowiedniego katalogu.
Podstawy: Uproszczę pierwszy akapit, aby był zrozumiały dla osób, które nie znają zmiennych środowiskowych ścieżki.
PODSUMOWANIE
Na koniec podaję kilka krótkich notatek, które zrobiłem podczas czytania dokumentacji. Gdy zaczniemy wspólnie realizować projekt, chcę samodzielnie przejść przez cały proces, aby sprawdzić, na czym popełniam błędy. I wykorzystać tę wiedzę, aby jeszcze bardziej uprościć dokumenty.
Na koniec, chociaż przeanalizowaliśmy tylko jeden projekt, nie sądzę, aby to zajęło więcej niż kilka tygodni. Jak już rozmawialiśmy w e-mailach, podczas naszej współpracy możemy zająć się kilkoma projektami.