Tworzenie dobrego ćwiczenia z programowania

Wstęp

Ćwiczenie z programowania to interaktywny samouczek napisany w składni języka Markdown. Nasze ćwiczenia z programowania publikujemy na stronie blocklycodelabs.dev. Dzięki połączeniu języka naturalnego, przykładów kodu i zrzutów ekranu, samouczek jest bardziej interesujący. Docelowy użytkownik ćwiczenia z programowania śledzi i uruchamia kod w trakcie odczytu.

Pisanie ćwiczeń z programowania to świetny sposób na pomaganie społeczności. W ten sposób możesz podzielić się swoją wiedzą i ułatwić życie kolejnemu deweloperowi, który napotka ten sam problem.

Co sprawia, że ćwiczenie w programowaniu jest świetne?

Świetne ćwiczenia z programowania muszą być zwięzłe i czytelne. Wyraźnie informuje użytkownika, co utworzy i czego się uczy, a także prowadzi użytkownika przez proces pisania i rozumienia kodu, który ma na celu wykonanie określonego zadania.

Przetwarzanie

Jeśli masz pomysł na ćwiczenie, możesz nas o nim poinformować, tworząc żądanie funkcji w repozytorium blockly-samples. Dodaj opis tego, czego chcesz uczyć i o tym, co chcesz utworzyć w ćwiczeniach z programowania. Omówimy ją i dopracujemy. Następnie możesz ją napisać i przesłać prośbę o jej wycofanie. Po zakończeniu sprawdzania członek zespołu Blockly opublikuje je.

Wskazówki dotyczące pisania

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

Na stronie Technical Pisanie One jest krótkie wprowadzenie do zagadnień technicznych.

Odbiorcy

  • Kto jest czytelnikiem docelowym?
  • Co już wie o korzystaniu z Blockly?
  • Czego próbują się nauczyć?

Konfiguracja

  • Jaka jest minimalna konfiguracja niezbędna do uruchomienia kodu przez użytkownika?

W razie potrzeby możesz opublikować kod startowy i kompletny kod w katalogu examples.

Struktura

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

  • Wprowadzenie
    • Czego się nauczysz
    • Co utworzysz
    • Wymagana wiedza
    • Instrukcje dotyczące konfiguracji
  • Krok 1: [tutaj należy wpisać tytuł]
    • Wyjaśnienie/motywacja
    • Przykładowy kod
    • Oczekiwane wyniki
    • (Opcjonalnie) Więcej wyjaśnień
  • ...
  • Krok 1. [Tu wstawić tytuł]
  • Podsumowanie
    • Zdobyte informacje
    • Stworzone przez Ciebie rozwiązania
    • Dodatkowe zasoby
    • Link do wypełnionego kodu (jeśli jest dostępny)

Możesz zrobić więcej niż 10 kroków, ale jeśli masz ich już 20, rozważ podzielenie jej na 2 ćwiczenia z programowania.

Styl pisania

  • Stosuj styl konwersacyjny.
  • Użyj nagłówków, aby jasno określić organizację
  • Używaj list punktowanych, by burzyć ściany tekstu.
  • Używaj obrazów i GIF-ów.

Styl kodu