Tworzenie ćwiczeń z programowania

Wprowadzenie

Codelab to interaktywny samouczek napisany w składni Markdown. Nasze laboratoria kodów publikujemy na stronie blocklycodelabs.dev. Aby uczynić samouczki bardziej interesujące, używamy w nich języka naturalnego, przykładowych fragmentów kodu i zrzutów ekranu. Użytkownik, do którego kierowany jest codelab, śledzi kod i uruchamia go w miarę czytania.

Tworzenie ćwiczeń to świetny sposób na wniesienie wkładu w rozwój społeczności. To sposób na udostępnienie swojej wiedzy i ułatwienie życia następnemu deweloperowi, który napotka ten sam problem.

Co sprawia, że Codelab jest tak skuteczne?

Dobre zajęcia z programowania są skoncentrowane i czytelne. W jasny sposób informuje użytkownika, co będzie tworzyć i czego się nauczy, a także prowadzi go przez proces tworzenia i rozumienia kodu, który pozwoli wykonać określone zadanie.

Proces

Jeśli masz pomysł na ćwiczenie z programowania, możesz go zgłosić, przesyłając prośbę o dodanie funkcji w repozytorium blockly-samples. Podaj opis tego, czego chcesz uczyć i co chcesz zbudować w ramach tego Codelab. Omówimy i udoskonalimy ten pomysł. Następnie możesz napisać i przesłać prośbę o przejęcie kodu źródłowego. Gdy przejdzie weryfikację, członek zespołu Blockly go opublikuje.

Wskazówki dotyczące pisania

Reszta tej strony zawiera wskazówki i pytania, które pomogą Ci napisać kodlab.

Zapoznaj się z Teksty techniczne 1, aby szybko zapoznać się z pisaniem tekstów technicznych.

Odbiorcy

  • Kim jest docelowy czytelnik?
  • Co już wiedzą o używaniu Blockly?
  • Czego próbują się nauczyć?

Konfiguracja

  • Jakie minimalne wymagania dotyczące konfiguracji musi spełnić użytkownik, aby uruchomić kod?

Jeśli to konieczne, możesz opublikować kod startowy i ukończony kod w katalogu examples.

Struktura

Jak w przypadku każdego tekstu, zacznij od konspektu. To dobra struktura dla większości ćwiczeń z programowania:

  • Wprowadzenie
    • Czego się nauczysz
    • Co utworzysz
    • Co musisz wiedzieć
    • Instrukcje konfiguracji
  • Krok 1. [Tytuł]
    • Wyjaśnienie/motywacja
    • Przykładowy kod
    • Oczekiwane wyniki
    • (Opcjonalnie) Więcej wyjaśnień
  • …
  • Krok 10. [Tutaj wpisz tytuł]
  • Podsumowanie
    • Czego się nauczyłeś
    • Co zostało utworzone
    • Dodatkowe materiały
    • Link do ukończonego kodu (jeśli jest dostępny)

Możesz mieć więcej niż 10 kroków, ale jeśli ich liczba zbliża się do 20, rozważ podzielenie projektu na 2 codelaby.

Styl pisania

  • Używaj stylu rozmowy.
  • Użyj nagłówków, aby uporządkować treść.
  • Używaj list punktowanych, aby dzielić długie teksty.
  • Używaj obrazów i GIF-ów.

Styl kodu