Tworzenie ćwiczeń z programowania

Wprowadzenie

Ćwiczenia z programowania to interaktywne samouczki napisane w składni Markdown. Nasze ćwiczenia w Codelabs publikujemy na stronie blocklycodelabs.dev. Zawierają one połączenie języka naturalnego, przykładowych fragmentów kodu i zrzutów ekranu, dzięki czemu są bardziej interesujące. Użytkownik, do którego skierowane są warsztaty, śledzi instrukcje i uruchamia kod w trakcie czytania.

Napisanie codelabu to świetny sposób na wniesienie wkładu w rozwój społeczności. To sposób na dzielenie się wiedzą i ułatwianie życia innym deweloperom, którzy napotkają ten sam problem.

Co sprawia, że codelab jest dobry?

Dobry codelab jest przejrzysty i łatwy do zrozumienia. Wyraźnie informuje użytkownika, co zbuduje i czego się nauczy, oraz prowadzi go przez proces pisania i rozumienia kodu, aby wykonać określone zadanie.

Proces

Jeśli masz pomysł na ćwiczenie z programowania, możesz nam o nim powiedzieć, przesyłając prośbę o dodanie funkcji w repozytorium blockly-samples. Opisz, czego chcesz nauczyć użytkowników i co zbudujesz w ramach tego przewodnika. Omówimy i dopracujemy ten pomysł. Następnie możesz ją opisać i przesłać żądanie scalenia. Po sprawdzeniu zostanie ona opublikowana przez członka zespołu Blockly.

Wskazówki dotyczące pisania

Pozostała część tej strony to zestaw wskazówek i pytań, które pomogą Ci w napisaniu codelabu.

Zapoznaj się z Technical Writing One, aby szybko poznać teksty techniczne.

Odbiorcy

  • Kim jest docelowy czytelnik?
  • Co już wiedzą o korzystaniu z Blockly?
  • Czego chcą się nauczyć?

Konfiguracja

  • Jakie jest minimalne wymagane ustawienie, aby użytkownik mógł uruchomić Twój kod?

W razie potrzeby możesz opublikować kod początkowy i ukończony kod w katalogu examples.

Struktura

Jak w przypadku każdego tekstu, zacznij od konspektu. To dobra struktura 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. [Title goes here]
  • Podsumowanie
    • Czego się dowiedziałeś
    • Co utworzysz
    • 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 masz ich 20, rozważ podzielenie ich na 2 samouczki.

Styl pisania

  • Używaj stylu konwersacyjnego.
  • Używaj nagłówków, aby zapewnić przejrzystość.
  • Używaj list punktowanych, aby podzielić bloki tekstu.
  • Używaj obrazów i GIF-ów.

Styl kodu