Viết lớp học lập trình

Giới thiệu

Lớp học lập trình là một hướng dẫn tương tác được viết bằng cú pháp Markdown. Chúng tôi xuất bản các lớp học lập trình tại blocklycodelabs.dev. Các lớp học lập trình sử dụng kết hợp ngôn ngữ tự nhiên, mã mẫu và ảnh chụp màn hình để tạo ra một trải nghiệm hướng dẫn thú vị hơn. Người dùng mục tiêu của một lớp học lập trình đang theo dõi và chạy mã khi họ đọc.

Viết một lớp học lập trình là một cách hiệu quả để đóng góp cho cộng đồng. Đây là cách để chia sẻ kiến thức và giúp cuộc sống của nhà phát triển tiếp theo gặp phải vấn đề tương tự trở nên dễ dàng hơn.

Điều gì tạo nên một lớp học lập trình hiệu quả?

Một lớp học lập trình chất lượng cao phải tập trung và dễ đọc. Nội dung này cho người dùng biết rõ họ sẽ xây dựng và học được những gì, đồng thời hướng dẫn người dùng viết và hiểu mã để hoàn thành một nhiệm vụ cụ thể.

Quy trình

Nếu có ý tưởng về một lớp học lập trình, bạn có thể cho chúng tôi biết bằng cách gửi một yêu cầu về tính năng trong kho lưu trữ blockly-samples. Thêm nội dung mô tả về những gì bạn muốn dạy và những gì bạn sẽ xây dựng trong lớp học lập trình. Chúng tôi sẽ thảo luận và tinh chỉnh ý tưởng này. Sau đó, bạn có thể viết và gửi yêu cầu kéo cho yêu cầu đó. Sau khi được xem xét, một thành viên trong nhóm Blockly sẽ xuất bản đề xuất đó.

Mẹo khi viêt

Phần còn lại của trang này là một bộ mẹo và câu hỏi hướng dẫn bạn viết lớp học lập trình.

Hãy xem Technical Writing One (Viết kỹ thuật 1) để biết thông tin giới thiệu nhanh về hoạt động viết kỹ thuật.

Đối tượng

  • Đối tượng độc giả mục tiêu là ai?
  • Họ đã biết những gì về cách sử dụng Blockly?
  • Họ đang cố gắng học điều gì?

Thiết lập

  • Người dùng cần thiết lập tối thiểu những gì để chạy mã của bạn?

Nếu hữu ích, bạn có thể xuất bản mã khởi đầu và mã hoàn chỉnh trong thư mục examples.

Cấu trúc

Giống như mọi hoạt động viết lách, hãy bắt đầu bằng một dàn ý. Đây là cấu trúc phù hợp cho hầu hết các lớp học lập trình:

  • Giới thiệu
    • Kiến thức bạn sẽ học được
    • Sản phẩm bạn sẽ tạo ra
    • Những điều bạn cần phải biết
    • Hướng dẫn thiết lập
  • Bước 1: [Tiêu đề ở đây]
    • Giải thích/động lực
    • Mã mẫu
    • Kết quả dự kiến
    • (Không bắt buộc) Giải thích thêm
  • ...
  • Bước 10: [Tiêu đề đặt tại đây]
  • Tóm tắt
    • Kiến thức bạn học được
    • Sản phẩm bạn đã tạo
    • Tài nguyên khác
    • Đường liên kết đến mã đã hoàn tất (nếu có)

Mặc dù có thể có hơn 10 bước, nhưng nếu có đến 20 bước, bạn nên cân nhắc chia thành 2 lớp học lập trình.

Văn phong

  • Sử dụng phong cách viết trò chuyện.
  • Sử dụng tiêu đề để sắp xếp rõ ràng.
  • Sử dụng danh sách có dấu đầu dòng để chia nhỏ các khối văn bản.
  • Sử dụng hình ảnh và ảnh GIF!

Kiểu mã