編寫優質程式碼研究室

簡介

程式碼研究室是以 Markdown 語法編寫的互動式教學課程。我們會在 blocklycodelabs.dev 發布程式碼研究室。程式碼研究室結合了自然語言、程式碼範例和螢幕截圖，為您打造更有趣的教學課程體驗。程式碼研究室的目標使用者如下：在閱讀過程中逐步執行程式碼。

撰寫程式碼研究室是對社群做出貢獻的絕佳方式。這是分享知識的方式，可以幫助下一位遇到相同問題的開發人員，讓他們的生活更加輕鬆。

怎樣才算是優質的程式碼研究室？

出色的程式碼研究室著重說明且易於閱讀。向使用者清楚指出即將建構的內容和學習內容，讓使用者透過撰寫並瞭解程式碼來完成特定工作。

處理

如果您對程式碼研究室有任何想法，可以在區塊範例存放區中提出功能要求，告訴我們您的想法。說明您要授課的內容，以及您在程式碼研究室中要建構的內容。我們將討論及修正這個想法。 接著，您可以編寫該程式，並提交提取要求。通過審查後，Blockly 團隊成員就會發布此應用程式。

書寫提示

本頁其餘部分將提供一系列的提示和問題，能夠引導您編寫程式碼研究室。

請參閱技術撰寫一，取得技術寫作的簡短介紹。

適用對象

  • 目標讀者是誰？
  • 他們已經知道如何使用 Blockly？
  • 他們想要學習什麼？

設定

  • 使用者執行程式碼所需的基本設定為何？

如有需要，您可以在 examples 目錄中發布範例程式碼和已完成的程式碼。

結構

就像撰寫任何內容一樣，請從大綱著手。這個結構適用於大多數程式碼研究室：

  • 簡介
    • 課程內容
    • 建構項目
    • 銷售須知
    • 設定說明
  • 第一步：[標題]
    • 說明/動機
    • 程式碼範例
    • 預期結果
    • (選用) 更多說明
  • ...
  • 第 10 步：[Title here]
  • 摘要
    • 您學到的內容
    • 建構內容
    • 其他資源
    • 已完成程式碼的連結 (如果有的話)

雖然可以設定超過 10 個步驟，但如果您碰到 20 次，請考慮將其分割為兩個程式碼研究室。

寫作風格

  • 運用對話式的書寫風格。
  • 使用標題讓內容清楚易懂。
  • 使用項目符號清單分隔文字牆。
  • 使用圖片和 GIF！

程式碼樣式

  • 您可以使用 ES5、ES6 或 TypeScript 編寫程式碼，但請告知讀取者開頭的內容。
  • 遵循 Google 樣式指南