There is a lot of good advice about details! 關於細節有很多好的建議！
Especially one that got my heart: 特別是其中一個打動我的：
> Some authors design their tutorials the way you’d give instructions for an origami structure. It’s a mysterious sequence of twists and folds until you get to the end, and then: wow, it’s a beautiful swan! > 有些作者設計他們的教學就像你指導摺紙一樣。它是一連串神秘的扭轉和摺疊，直到你到達最後，然後：哇，它是一隻美麗的天鵝！
> A grand finale might be fun for origami, but it’s stressful for the reader." > 盛大的結局對摺紙來說可能很有趣，但對讀者來說卻很令人緊張。"
Yes, a lot of tutorials are puzzle games. You need to guess other tools to install, which are obvious to the author, but not everyone. 是的，很多教學都是益智遊戲。你需要猜測要安裝哪些其他工具，這些工具對作者來說很明顯，但並非每個人都清楚。
I would add a few things: 我想補充幾點：
* Have two types of examples - minimal and the most typical (one is to show the essence without distraction, the second to serve as a practical starting point)
* Always provide the full code sequence to run code; if there are any assumptions, these should be listed explicitly (e.g. "it needs Node 22"); you hinted a bit, but since many tutorials miss that, it deserves attention. * 提供兩種範例——最小化和最典型（一種是用於顯示本質而不分心，另一種是用作實用的起點）*始終提供完整的程式碼序列以執行程式碼；如果有任何假設，這些都應明確列出（例如，「需要 Node 22」）；你稍微暗示了一下，但由於許多教學都錯過了這一點，因此值得關注。
Even better, if it is possible to combine it into one point and make it runnable. For example, for a package I had been developing, livelossplot, I made Jupyter Notebooks runnable in Colab: 更好的是，如果可以將其合併成一點並使其可執行。例如，對於我一直在開發的一個套件 livelossplot，我在 Colab 中製作了可執行的 Jupyter Notebooks：
This is something that resonates / I really strive for. Cutting corners / over simplifying intentionally to have a "working" (poor) usable step along the way, that you can then improve / fix and explain why you can't / shouldn't cut those corners. Not applicable to all tutorials, but I like this approach because it feels more like an exploratory learning experience rather than prescriptive instruction. 這是一件引起共鳴的事情／我真正努力追求的。故意偷工減料／過度簡化，以便在過程中有一個「可行」（質量差）的可使用步驟，然後你可以改進／修復並解釋為什麼你不能／不應該偷工減料。並非適用於所有教學，但我喜歡這種方法，因為它感覺更像是一種探索式學習體驗，而不是指令式教學。
I hope that plenty of developers read this, especially folks on open source projects who don't have dedicated documentation people. There's so much bad documentation out there, and many of these tips are key. 我希望有很多開發人員閱讀這篇文章，尤其是開源專案中沒有專門文件人員的人。有很多糟糕的文件，這些技巧中的許多都是關鍵。
A couple more of my own: 我自己還有另外幾點：
TEST YOUR DOCS 測試你的文件
As @codetrotter suggests in another comment, run through your own tutorial with a fresh VM and follow it closely; you'll almost certainly find something to improve. 正如 @codetrotter 在另一則評論中所建議的，使用新的虛擬機器瀏覽你自己的教學，並仔細遵循它；你幾乎肯定會發現一些需要改進的地方。
But this works better if you have someone else try it out instead: get on a video call with them, have them share their screen and speak their thoughts out loud, and most importantly, don't help them. You're trying to find out if they can complete this without additional help. (Yes, it's a usability test.) 但如果你讓其他人試用，效果會更好：與他們進行視訊通話，讓他們分享他們的螢幕並大聲說出他們的想法，最重要的是，不要幫助他們。你試圖找出他們是否可以在沒有額外幫助的情況下完成這項工作。（是的，這是一個可用性測試。）
BETTER SOFTWARE MAKES SIMPLER TUTORIALS 更好的軟體使教學更簡單
The article's rule about "let computers evaluate conditional logic" is a good one, but there are multiple places to fix that problem. Sometimes it's in the tutorial, sometimes it's in the software product itself. When the tutorial makes the reader do complex work, it may be a sign that the software has UX issues. You may not be in a position to fix it, but you can probably file an issue. 文章中關於「讓電腦評估條件邏輯」的規則很好，但是有多個地方可以解決這個問題。有時它在教學中，有時它在軟體產品本身中。當教學讓讀者做複雜的工作時，這可能表示軟體存在 UX 問題。你可能無法修復它，但你可能可以提交一個問題。
For the example in the article: could you make the same package name work on all three Debian versions? It'd certainly improve the user experience, and probably make the installation process more resilient. 對於文章中的例子：你能讓相同的套件名稱在所有三個 Debian 版本上都能工作嗎？這肯定會改善使用者體驗，並可能使安裝過程更具彈性。
I spend a great deal of time, testing the hell out of my supporting material. 我花了很多時間測試我的輔助材料。
I usually supply a GitHub repo or gist, with either a full app, or a playground. In many cases, I’ll have a full app, already running, with just one source file, that we’ll be modifying. This may be in a tagged GitHub repository or gist, with tags, denoting steps[0]. In other cases, I’ll supply a zip file, with everything in it[1]. 我通常提供一個 GitHub 儲存庫或 gist，其中包含完整的應用程式或遊樂場。在許多情況下，我將有一個完整的應用程式正在執行，只有一個原始檔，我們將修改它。這可能位於標記的 GitHub 儲存庫或 gist 中，並帶有標記，表示步驟[0]。在其他情況下，我將提供一個 zip 檔案，其中包含所有內容[1]。
I can take a month, developing a tutorial that can be run in an hour. 我可以花一個月時間，開發一個可在一個小時內完成的教學課程。
Teaching is hard. A good trainer spends many hours, preparing for relatively short classes. It’s sort of like playing a concert; you only get one chance, so preparation is key. Also, in tech, the students are often more accomplished than the teacher. It can be a tough room. 教學很難。一位優秀的培訓師會花很多時間準備相對較短的課程。這有點像演奏音樂會；你只有一次機會，所以準備工作至關重要。此外，在科技領域，學生往往比老師更有經驗。這可能是一個艱難的場合。
That said, I have attended some valuable tutorials, in which the teacher did a terrible job, preparing. It’s just that I don’t work that way, myself. 儘管如此，我參加過一些有價值的教學課程，其中老師的準備工作做得非常糟糕。只是我自己不這樣做。
The main reason that I write tutorials, is to teach myself. I don’t think anyone else really pays much attention to my work[2]. I have presented a few “official” classes[1], but mostly, I work on my own. I have, actually, been teaching for decades, in small, short, seminar form; mostly for non-technical stuff. 我撰寫教學課程的主要原因是為了自學。我不認為其他人真的會太注意我的作品[2]。我已經教授了一些「正式」的課程[1]，但大多數情況下，我都是自己工作。事實上，我已經進行了數十年的教學，以小型、簡短的研討會形式進行；主要是關於非技術性內容。
> But this works better if you have someone else try it out instead > 但如果您讓其他人試用，效果會更好
1000x yes. 非常同意 (1000 倍)。
Yoz, you are wise and while what you say may seem like an obvious thing, it isn't. I was once in the unfortunate position of having to write manuals for software I did not design, so I went through it thinking I was the "average user." As it turns out, I was under the false impression that my documentation was perfectly understandable to anyone, to the point where they could sit down, rtfm and go. Yoz，您很明智，雖然您說的話似乎是一件顯而易見的事情，但事實並非如此。我曾經不幸地必須為自己沒有設計的軟體撰寫手冊，所以我一邊寫一邊認為自己是「普通使用者」。結果，我錯誤地認為我的文件對任何人都完全易於理解，他們可以坐下來，閱讀手冊然後開始使用。
Boy was I wrong. 我錯得離譜。
I later got into an area of work where I had to help individuals with cognitive disabilities adapt to new workflows in factory settings. One of the exercises I had to do to earn my certification in this field was to imagine an individual that had never seen a broom or dustpan before, then use only photos to explain how to sweep a floor. It's far more challenging than you think. I realized that not only was I making the mistake of explaining things to myself, but I was also assuming that I could put myself in someone else's shoes and interpret my own instructions with fresh eyes. This, as it turns it, was folly. 我後來從事一個領域的工作，我必須幫助有認知障礙的個人適應工廠環境中的新工作流程。為了獲得這個領域的認證，我必須做的練習之一是想像一個從未見過掃帚或簸箕的人，然後只使用照片來解釋如何掃地。這比你想像的要困難得多。我意識到，我不僅犯了向自己解釋事情的錯誤，而且還假設我可以設身處地為他人著想，並以全新的眼光來詮釋我自己的說明。結果證明，這是愚蠢的。
That experience propelled my documentation forward by leaps and bounds, though. In my current position, I came up with over a dozen single-page instructions to resolve issues customers were having with our products that, previous to my working here, generally took an hour-long phone call, eating up time and resources on both ends. Each page was tested with a coworker or willing customer that had never worked with the product before with welcomed feedback. The result was a significant drop in time wasted on these otherwise simple fixes, allowing us to redirect our big guns at the more complex issues that arise. 然而，那次經歷使我的文件編寫能力突飛猛進。在我目前的工作中，我想出了十多個單頁說明來解決客戶使用我們產品時遇到的問題，在我來這裡工作之前，這些問題通常需要一個小時的電話才能解決，浪費了雙方的時間和資源。每一頁都經過與從未使用過該產品的同事或自願客戶一起測試，並獲得了寶貴的回饋。結果是顯著減少了浪費在這些原本簡單的修復上的時間，使我們能夠將主要精力集中在更複雜的問題上。
For anyone interested in the kinds of pitfalls we fall into when we think we can bridge the gap between two minds with our "exact" instructions, check out this video. I think it does a wonderful job of conveying these problems in communication in a really fun way. 對於任何有興趣了解我們在認為自己可以用我們的「精確」說明來彌合兩者之間差距時會遇到的陷阱的人，請觀看此影片。我認為它非常出色地以一種非常有趣的方式傳達了這些溝通問題。
> But this works better if you have someone else try it out instead: get on a video call with them, have them share their screen and speak their thoughts out loud, and most importantly, don't help them. You're trying to find out if they can complete this without additional help. (Yes, it's a usability test.) > 但如果您讓其他人試用，效果會更好：與他們進行視訊通話，讓他們分享他們的螢幕並大聲說出他們的想法，最重要的是，不要幫助他們。您試圖找出他們是否可以在沒有額外幫助的情況下完成此任務。(是的，這是一個可用性測試。)
If you take _nothing_ else away from the article and/or this thread, take this away! 如果你從這篇文章和/或這個討論串中只帶走一樣東西，就帶走這個！
I pride myself on the quality of docs that I produce and my "secret" is enlisting guinea pigs. Before linking somebody to the doc(s) they need, I'll send them a message akin to "if you get stuck at literally any point or encounter literally any error or shell output that does not match what's in the docs, stop and message me. We'll work it out together and the docs will be better for the next person" 我為自己製作的文件品質感到自豪，而我的「秘密」就是徵募小白鼠。在將某人連結到他們需要的文件之前，我會發送類似這樣的訊息：「如果您在任何一點上卡住了，或遇到任何錯誤或 shell 輸出與文件中的內容不符，請停止並給我發訊息。我們將一起解決這個問題，文件對下一個人來說會更好」
Do that a few times and you have a high-quality document that'll cover the process and any known edge cases. 重複操作幾次，就能得到一份高品質的文件，涵蓋整個流程和任何已知的邊緣情況。
The critical bit is that the person that needs the doc is already not having an awesome day; make it clear to them that you're here to help and not in a "come to me after you've spent 2 hours trying to make it work" way. 關鍵一點是，需要這份文件的人已經度過了糟糕的一天；要讓他們清楚地知道，你是在這裡幫助他們，而不是以「在你花了兩個小時嘗試使其工作後再來找我」的方式。
I've been thinking for a long time about anti-patterns I see when following software tutorials, so I put together this list of things I think differentiate good tutorials from poor ones. 我長期以來一直在思考在遵循軟體教學時看到的反模式，因此我整理了這個清單，列出我認為好的教學與不好的教學之間的區別。
I'm happy to hear any feedback on this list or hear about other things I should include. 我很樂意聽到任何關於這個清單的反饋，或聽到我應該包含的其他事項。
The article gives some useful tips. But (if I may) I'll disagree with a couple of small parts: 這篇文章提供了一些有用的技巧。但是（如果可以的話）我不同意其中幾個小部分：
> Write for beginners > 為初學者撰寫
I prefer "write for your audience". For example, in the first lesson for my canvas library[1], I'm aiming at an audience of front-end developers - they should know how to code a very basic HTML page and start a local server to view it. 我更喜歡「為你的受眾撰寫」。例如，在我的畫布函式庫[1]的第一課中，我的目標受眾是前端開發人員——他們應該知道如何編寫一個非常基本的 HTML 頁面，並啟動一個本地伺服器來查看它。
Of course, my lesson fails here. I'll add a line near the top of the copy to say who the intended audience is, and a link to the MDN frontend developer course[2] for any complete beginners who (somehow) found the lesson. 當然，我的課程在這方面失敗了。我會在複製項的頂部附近添加一行文字來說明目標受眾是誰，並為任何（不知何故）找到該課程的完全初學者提供指向 MDN 前端開發人員課程[2]的連結。
> Make code snippets copy/pasteable > 使程式碼片段可複製/貼上
Maybe I'm an outlier but, when I blindly copy-paste code, I rarely learn about that code: it's just some magic that I feed into the computer to get results. I learn better when the tutorial forces me to type out the code (and I do nasty things in my tutorial to persuade learners to type rather than copy-paste). 也許我是一個例外，但是，當我盲目複製貼上程式碼時，我很少學習到關於該程式碼的知識：它只不過是我輸入電腦以獲得結果的一些魔法。當教學迫使我輸入程式碼時，我學得更好（我在我的教學中做了一些不好的事情來說服學習者輸入而不是複製貼上）。
I am with you on #1 -- I write a lot of tutorials but I'm not trying to help you learn how to open a terminal. I'd prefer to lose those readers up front rather than frustrate them for 30 minutes. 我同意你的看法 #1 -- 我寫了很多教學文章，但我不想教你如何開啟終端機。我寧願一開始就失去這些讀者，也不願讓他們感到沮喪 30 分鐘。
#2 is too far. If people want to misuse your stuff, shame on them, but don't boobie trap it! #2 太過火了。如果人們想要濫用你的東西，那是他們的錯，但不要設置陷阱！
Yeah, I think I need a different wording for "write for beginners." It's not "write for beginners to programming" but "write for beginners to your particular subject." 是的，我認為我需要為「為初學者編寫」改用不同的措辭。它不是「為程式設計初學者編寫」，而是「為你特定主題的初學者編寫」。
Like in your case, you're writing for frontend developers who are not new to making webpages, but they're beginners at using the canvas element. 就像你的例子一樣，你是在為前端開發人員編寫文章，他們並不算是網頁製作新手，但他們是使用 canvas 元素的新手。
My main request, which I know is a big ask: 我的主要請求，我知道這是一個很大的要求：
Actively deprecate. 主動棄用。
I don't expect authors to write a new tutorial whenever the syntax for doing something changes. But it would be unbelievably helpful if you could just stick a banner on the top of a piece saying "this doesn't work anymore" as soon as that's true (which, unfortunately, is usually about three months after you write it) 我不期望作者在執行某項操作的語法更改時編寫新的教學文章。但如果你能在程式碼片段的頂部貼上橫幅，寫著「這已經不再有效了」，那就太好了（不幸的是，這通常在你寫完程式碼大約三個月後才會發生）
I have a minor nit to pick. I actually prefer when tutorials provide the prompts for all code snippets for two reasons: 我有一個小細節要挑剔。我實際上更喜歡教學文章為所有程式碼片段提供提示，原因有二：
1. Many tutorials reference many languages. (I frequently write tutorials for students that include bash, sql, and python.) Providing the prompts `$`, `sqlite>` and `>>>` makes it obvious which language a piece of code is being written in. 1. 許多教學文章參考多種語言。（我經常為學生編寫包含 bash、sql 和 python 的教學文章。）提供提示符號 `$`、`sqlite>` 和 `>>>` 可以清楚地表明程式碼是用哪種語言編寫的。
2. Certain types of code should not be thoughtlessly copy/pasted, and providing multiline `$` prompts enforce that the user copy/pastes line by line. A good example is a sequence of commands that involves `sudo dd` to format a harddrive. But for really intro-level stuff I want the student/reader to carefully think about all the commands, and forcing them to copy/paste line by line helps achieve that goal. 2. 某些類型的程式碼不應該不假思索地複製/貼上，提供多行提示可以強制使用者逐行複製/貼上。一個很好的例子是一系列涉及 `sudo dd` 格式化硬碟的命令。但對於真正的入門級內容，我希望學生/讀者仔細思考所有命令，強制他們逐行複製/貼上有助於實現這個目標。
That said, this is an overall good introduction to writing that I will definitely making required reading for some of my data science students. When the book is complete, I'll be happily buying a copy :) 儘管如此，這仍然是一個很好的寫作入門介紹，我肯定會把它作為我一些數據科學學生的必讀資料。書完成後，我會很樂意購買一本 :)
> Certain types of code should not be thoughtlessly copy/pasted, and providing multiline `$` prompts enforce that the user copy/pastes line by line. > 某些類型的程式碼不應該不假思索地複製/貼上，提供多行提示可以強制使用者逐行複製/貼上。
I hardcore oppose this kind of thing, for the same reason I oppose people putting obstacles in the way of curl-to-bash. 我強烈反對這種做法，原因與我反對人們在 curl 到 bash 的過程中設置障礙相同。
Adding the prompt character doesn’t make people think, it just makes people press backspace. Frequently I’m reading a tutorial because I’m trying to assemble headless scripts for setting up a VM and I really just need verbatim lines I can copy/paste so I know I’ve got the right arguments. 新增提示字元並不會讓人思考，只會讓人按退格鍵。我經常閱讀教學文章是因為我試圖組裝無頭指令碼來設定虛擬機器，而我真正需要的只是我可以複製/貼上的逐字逐句的程式碼，這樣我才能確保我有正確的參數。
>Many tutorials reference many languages. (I frequently write tutorials for students that include bash, sql, and python.) Providing the prompts `$`, `sqlite>` and `>>>` makes it obvious which language a piece of code is being written in. >許多教學文章參考多種語言。（我經常為學生編寫包含 bash、sql 和 python 的教學文章。）提供提示符號 `$`、`sqlite>` 和 `>>>` 可以清楚地表明程式碼是用哪種語言編寫的。
I think it's fine to show the prompt character, but I think it's the author's job to make sure that copy/paste still works. I've seen a lot of examples that use CSS to show the prompt or line number without it becoming part of copied text, and I'm highly in favor of that. 我認為顯示提示字元是可以的，但我認為作者有責任確保複製/貼上仍然有效。我見過很多例子使用 CSS 顯示提示或行號，而不會讓它成為複製文字的一部分，我非常贊成這樣做。
I think if I had to choose between breaking copy/paste and making the language obvious with the prompt character, I'd exclude the prompt, but I think that's a matter of taste. 我認為如果我必須在破壞複製/貼上和使用提示字元使語言清晰之間做出選擇，我會排除提示，但我認為這是一個品味問題。
>Certain types of code should not be thoughtlessly copy/pasted, and providing multiline `$` prompts enforce that the user copy/pastes line by line. A good example is a sequence of commands that involves `sudo dd` to format a harddrive. But for really intro-level stuff I want the student/reader to carefully think about all the commands, and forcing them to copy/paste line by line helps achieve that goal. >某些類型的程式碼不應該不假思索地複製/貼上，提供多行提示可以強制使用者逐行複製/貼上。一個很好的例子是一系列涉及 `sudo dd` 格式化硬碟的命令。但對於真正的入門級內容，我希望學生/讀者仔細思考所有命令，強制他們逐行複製/貼上有助於實現這個目標。
Yeah, I agree about preventing the reader from copy/pasting something dangerous. 是的，我同意避免讀者複製/貼上危險內容。
In tutorials that require a reboot, I'll never include a reboot command bunched in with other commands because I don't want the user to do it by mistake. And I agree for something like `dd`, you'd want to present it in a way to make it hard for the reader to make mistakes or run it thoughtlessly. 在需要重新啟動的教學中，我永遠不會將重新啟動命令與其他命令放在一起，因為我不希望使用者不小心執行它。我同意，對於像`dd`這樣的命令，您需要以一種方式呈現它，以使讀者難以犯錯或無意識地執行它。
> I've seen a lot of examples that use CSS to show the prompt or line number without it becoming part of copied text, and I'm highly in favor of that. > 我看過很多例子使用 CSS 來顯示提示或行號，而不會讓它成為複製文字的一部分，我非常贊成這樣做。
This is unfortunately not compatible with writing the tutorial in markdown to be rendered on github. 不幸的是，這與在 GitHub 上渲染的 Markdown 教學不兼容。
I'm not sure about that. There are markdown rendering engines where you can specify the language of a codeblock and it will render with specific CSS based on the language. So you can do something like ```bash ... ``` and it will show the code with newlines prefixed by "$" 我不確定。有些 Markdown 渲染引擎允許您指定程式碼區塊的語言，它將根據語言渲染特定的 CSS。因此，您可以執行類似 ```bash ... ``` 的操作，它將顯示程式碼，並在每一行前面加上 "$"
AFAIK specifying a language only makes a difference for syntax highlighting. I have never seen a markdown processor that would add prompts to the code based on the specified language. 據我所知，指定語言只會影響語法高亮顯示。我從未見過會根據指定的語言在程式碼中添加提示的 Markdown 處理器。
Syntax highlighting is just CSS. There's nothing stopping you from adding your own custom CSS to the code block which will prefix lines with the prompts. 語法高亮顯示只是 CSS。沒有任何東西阻止您向程式碼區塊添加自定義 CSS，它會在行首加上提示。
I always include a $ in front of terminal commands (and > for Windows). 我總是在終端命令前面加上 $（Windows 上使用 >）。
My books are Python related, so there is code that runs in putting and code that runs in other environments. 我的書與 Python 相關，所以有些程式碼在 Python 環境中運行，有些程式碼在其他環境中運行。
I guess I'm not really writing "tutorials" in the sense of webpages, so I'm less concerned with copy paste working and more concerned with clarity. 我想我並沒有真正撰寫網頁形式的「教學」，所以我比較不擔心複製貼上是否有效，而更關心清晰度。
This advice reminds me of my list of rules for technical presentations. One of which is no live coding. Record your live coding if you need it. Live coding serves no one, and if you record it, it's there and it works. 這個建議讓我想起了我的技術簡報規則清單。其中之一是不進行現場編碼。如果您需要，請錄製您的現場編碼。現場編碼對任何人都沒有幫助，如果您錄製它，它就在那裡，而且有效。
I do not know of a case where a recording is not better. 我不知道有任何情況錄製不如現場演示。
"Oh, but what if you have to update what you do" 「喔，但是如果必須更新您的操作怎麼辦？」
Then when you practice it for your presentation, record it and put that in. 那麼，當您為簡報練習時，請錄製它並放入其中。
"Oh, but I don't want to edit the video" 「喔，但是我不想要編輯影片。」
If you have to edit the video to take out the useless parts, you are just leaving the useless parts in during the live coding. 如果您必須編輯影片以去除無用的部分，那麼您只是在現場編碼過程中保留了無用的部分。
"Oh, but I enjoy it" 「喔，但是我很享受它。」
The presentation is for the audience. 簡報是為了觀眾。
"What if they ask a question" 「如果他們提問怎麼辦？」
If they ask a question about what you did, you can easily replay it. 如果他們問你做了什麼，你可以輕鬆地重播它。
If they ask a question beyond that, you can also dive into live coding, but that's the exception. 如果他們問的問題超出這個範圍，你也可以深入到現場編碼，但那是例外。
Really good advice there. Thank you for writing this. 非常好的建議。謝謝你寫這個。
I've written several in-house tutorials to our internal product, and I've come to internalize your advice somehow. 我已經為我們的內部產品撰寫了幾個內部教程，不知不覺中已經內化了你的建議。
IMO it's mostly about empathy. I remember myself as a newbie perplexed by this product and try to write to my younger self. I also make a point to always spend a lot of time with new hires and get their feedback and their viewpoint. 我認為這主要關乎同理心。我記得自己作為新手時對這個產品感到困惑，並試著寫給我年輕時的自己。我也特別注重花很多時間與新員工一起工作，並獲得他們的反饋和觀點。
Sometimes this advice of describing what something is and why you'd use it is helpful. Other times I already know what it's for and just want to use it, and don't like having to slog through descriptions that don't help with implementation. There is no universal right or wrong answer here, since it will depend on who is reading your tutorial, what their level of expertise is, and what they need. 有時，描述某事物是什麼以及為什麼要使用它的建議很有幫助。其他時候，我已經知道它的用途，只想使用它，並且不喜歡不得不仔細閱讀那些無助於實作的描述。這裡沒有放之四海而皆準的正確或錯誤答案，因為它取決於誰在閱讀你的教程、他們的專業水平以及他們的需求。
A tutorial can provide the best of both worlds by putting the background stuff of each section in a sidebar, so the reader can easily skip it or delve more deeply if they wish. 教程可以提供兩全其美的方案，將每個章節的背景資料放在側邊欄中，這樣讀者可以輕鬆跳過它，或者如果他們願意可以更深入地探討。
I actually don’t like the example with Djano and JS: too much bad/fake SEO compounded by Googles enshitification mean that very specific search terms for specific technologies get drowned out by generic word salads like “organising and structuring djano projects”. 我其實不喜歡 Django 和 JS 的例子：太多的不良/虛假 SEO 加上 Google 的劣質化，意味著針對特定技術的非常具體的搜尋詞彙會被像「組織和架構 Django 專案」這樣的通用詞彙沙拉淹沒。
There’s probably a million of those already. 可能已經有數百萬個這樣的例子了。
Thanks for reading and for the feedback. 感謝您的閱讀和反饋。
Yeah, I see what you're saying. I had this article[0] in mind, which is a well-written article and ranks #1 for "organize front end code django" on Google. None of the other results are close in relevance or quality. 是的，我明白你的意思。我想到這篇文章[0]，這是一篇寫得很好的文章，在 Google 上排名第一的關鍵字是「組織前端程式碼 Django」。其他結果在相關性或品質上都遠不及它。
But I guess that example could be confusing for readers who aren't familiar enough with Django to know why structuring the frontend is a hard problem that not many people write about. 但我猜這個例子可能會讓那些不夠熟悉 Django 以至於不知道為什麼前端架構是一個許多人都不會寫到的困難問題的讀者感到困惑。
For those who can't find other people as your guinea pig, this is the trick I use: After finishing your tutorial, just wait for a few days, and try following it yourself, in a fresh env. 對於那些找不到其他人作為你的小白鼠的人來說，這是我的訣竅：完成你的教程後，只需等待幾天，然後在新的環境中嘗試自己遵循它。
I'm cursed (blessed?) with fish memory so after a few days I forgot everything I wrote. 我被（幸運地？）詛咒了金魚記憶，所以幾天后我就忘記了我寫的所有東西。
> Tutorials often forget to mention some key detail, preventing readers from replicating the author’s process. > 教程經常忘記提及一些關鍵細節，阻止讀者複製作者的流程。
I also find this sometimes. 我有時也會發現這個問題。
A high quality tutorial on the other hand, is often one where the author bothered to set up a fresh VM and follow their own guide step by step to confirm that everything works as described. This way the author avoids unintentionally forgetting to mention additional dependencies that have to be installed and additional config files that need to be tweaked in order for the steps to work. 另一方面，高品質的教程通常是作者費心設置了一個新的虛擬機器並一步一步地遵循自己的指南以確認一切都能按描述工作。這樣，作者就能避免無意中忘記提及必須安裝的其他相依性以及需要調整才能使步驟起作用的其他組態檔案。
Extending on the copy-pasteable snippets, another big improvement (flaw to avoid) is to include all imports to the code snippets. 延續可複製貼上程式碼片段，另一個很大的改進（要避免的缺陷）是將所有導入包含到程式碼片段中。
I thought "Keep your code in a working state" would be discussing how to keep code working when some dependency changes. What was covered is valuable advice, but I'd like some exploration on keeping the published code cohesive under refactoring and refinement away from the text. 我原以為「保持程式碼運作狀態」會討論當某些相依性改變時如何保持程式碼運作。所涵蓋的內容是有價值的建議，但我希望進一步探討如何在重構和改進過程中保持已發佈程式碼的一致性。
For example, if I'm P. Shirley and I've written a book (with code) about following light rays between a virtual camera and virtual objects. I have refactored some code to be more clear. Of course, I have iterated on this code to verify it remains correct, but the related text isn't affected. I have to remember where to paste this new code. Unless the documentation had some kind of reference to the specific file, lines, and/or function to render into the text. 例如，如果我是 P. Shirley，並且我寫了一本關於追蹤虛擬攝影機和虛擬物體之間光線的書（包含程式碼）。我重構了一些程式碼以使其更清晰。當然，我已經反覆運算此程式碼以驗證其仍然正確，但相關文字沒有受到影響。我必須記住將此新程式碼貼到哪裡。除非文件包含對特定檔案、行和/或函數的某種參考以呈現到文字中。
What's the advice for best practices here? 此處的最佳實務建議是什麼？
Make the tutorial text include the code verbatim from a working repo that passes CI. No pasting necessary. Sure you still have to verify that the tutorial text aligns with the code changes, but you don't have to do anything manual to update the code in the tutorial. 使教學文字包含來自通過 CI 的運作儲存庫中的程式碼逐字稿。無需貼上。當然，您仍然必須驗證教學文字與程式碼變更一致，但您無需手動更新教學中的程式碼。
As an actual example of this, here's a plugin for Remark that allows us to import specific functions from a rust source file. https://github.com/ratatui/ratatui-website/blob/main/src/plu... If the source code fails to compile, we get a CI error (in the rust checks). If the source code changes in a way where the import is no longer correct, we get a CI error (in the npm checks). 以下是一個實際示例，這是一個 Remark 插件，允許我們從 rust 原始檔導入特定函數。https://github.com/ratatui/ratatui-website/blob/main/src/plu... 如果原始碼編譯失敗，我們會收到 CI 錯誤（在 rust 檢查中）。如果原始碼以導入不再正確的方式更改，我們會收到 CI 錯誤（在 npm 檢查中）。
I've actually contributed to the Ray Tracing In one Weekend project. The process is pretty manual. The book is actually written HTML, and the code snippets are duplicated from the source (not linked in). Before release, it's a manual process to go through each book and read/build it from scratch. 我實際上為《週末光線追蹤》專案貢獻過程式碼。這個過程相當手動。這本書實際上是用 HTML 編寫的，程式碼片段是從原始碼複製的（沒有連結）。在發佈之前，需要手動檢查每一本書並從頭開始讀取/構建它。
In my opinion, the open source nature really is the key thing here. Most of the issues are small things (typos, confusing verbage, etc). So it get's refined as people read it. 我認為，開源的本質才是關鍵。大多數問題都是小問題（錯字、含糊不清的措辭等）。因此，隨著人們閱讀它，它會不斷完善。
Some people embed code in a way that’s similar to a test and then have a process to run/test all the embedded code. 有些人以類似於測試的方式嵌入程式碼，然後有一個過程來運行/測試所有嵌入的程式碼。
Given that most examples are relatives small, one could leverage org-babel[1] and write the tutorial with executable code, and go straight to .PDF! 鑑於大多數範例都相對較小，可以使用 org-babel[1] 並使用可執行程式碼編寫教學，然後直接轉換為 .PDF！
A developer who’s new to the React web framework won’t understand terms like “JSX transpilation” or “reconciliation engine.” They probably also won’t understand “SPA,” “soft reload,” or “virtual DOM” unless they’ve worked with other JavaScript frameworks. 一位剛接觸 React 網頁框架的開發人員不會理解「JSX 轉譯」或「調和引擎」等術語。除非他們曾使用其他 JavaScript 框架，否則他們可能也不理解「SPA」、「軟重新載入」或「虛擬 DOM」。
Unfortunately if you don’t use that, your beginners will have hard time to believe you are “guru” that they seek. Like if they find other guys tutorial with fancy words they will flock there - looking for some magic trick or some revelation that will hopefully come down on them while reading bunch of hard words without understanding. 不幸的是，如果您不這樣做，您的初學者將很難相信您是他們尋求的「大師」。例如，如果他們發現其他人的教學使用了花哨的詞彙，他們就會蜂擁而至——尋找一些魔術技巧或一些啟示，希望在閱讀一堆難懂的詞彙時能降臨在他們身上。
Most tutorials are like that for this reason. If you want to teach people author is right - if you are cynical and just want to earn money on a tutorial that’s a different thing. One upside - people quitting “hard” course most likely will be embarrassed to ask for return of money as they would feel it is their fault they did not learn as topic is hard. 大多數教學都是出於這個原因。如果您想教導人們作者是對的——如果您很悲觀，只想從教學中賺錢，那就是另一回事了。一個好處——退出「困難」課程的人很可能不好意思要求退款，因為他們會覺得這是他們自己的錯，因為他們沒有學到東西，因為主題很難。
If they feel topic was easy and they did not learn, that’s probably guy making tutorial not knowing enough. 如果他們覺得主題很容易，而他們沒有學到東西，那可能是教學的人知識不夠。
Thank you for this. I want to also reference diataxis [0], a systematic approach to technical documentation authoring, which I think has some good advice on the subject of tutorials. 感謝您的資訊。我也想參考 diataxis [0]，這是一種系統化的技術文件撰寫方法，我認為它對教學主題有一些很好的建議。
My pet peeve is code along the lines of: 我最討厭的程式碼如下：
if err != nil {
// handle errors
}
Or: 或：
try {
// something that can fail
} catch (Exception e) {
// handle exceptions here
}
It's usually laziness from the author, but not stating _what types_ of error may occur and how should typically handle them is a plague on documentation and tutorials. 這通常是作者的懶惰，但沒有說明可能發生的_錯誤類型_以及如何通常處理它們，這在文件和教學中是一種常見問題。
Very good stuff. Going to consult this as I build personal and work projects. Working at a huge org right now and its amazing how many crucial details are missed in the tutorials that we have for internal things we depend on 非常好的內容。在我建立個人和工作專案時會參考它。現在在一間大型組織工作，令人驚訝的是，我們用於我們依賴的內部事物的教學中錯過了多少關鍵細節。
> As soon as possible, show a working demo or screenshot of what the reader will create by the end of your tutorial. > 儘快展示讀者在完成教學後將建立的實際範例或螢幕截圖。
For this reason I am building a new way of writing coding tutorials, with the possibility of writing and running code snippets into the web browser including graphical apps: https://exalib.com 出於這個原因，我正在建立一種新的編寫程式碼教學的方法，可以將程式碼片段和圖形應用程式寫入並執行到網頁瀏覽器中：https://exalib.com
I think many of these rules are good, but that there's a too strong focus on ensuring that shell snippets are copy-pasteable without inspection. This comes at the detriment of other considerations, and I think some of the advice goes too far. 我認為許多這些規則都很好，但是過於強調確保 shell 片段可以直接複製貼上而無需檢查。這以犧牲其他考量為代價，而且我認為有些建議過於極端。
Especially so when it comes to the different package names on different Debian versions: what originally was a oneliner is now fifteen lines long with six different branches. What should the reader do if the copy-pasted code fails? How do they know which part failed? What is an "/etc/os-release"? Yes, the happy path becomes simpler, but the reader will struggle to recover from any errors. 特別是在不同 Debian 版本上的不同套件名稱方面：最初是一行程式碼，現在卻變成了包含六個不同分支的十五行程式碼。如果複製貼上的程式碼失敗，讀者應該怎麼辦？他們如何知道哪一部分失敗了？什麼是「/etc/os-release」？是的，順利執行的路徑變得更簡單，但讀者將難以從任何錯誤中恢復。
I thought that using Makefile targets was the shortest friendliest to show what a project can do. Turns out make and Makefiles can be mysterious when they fail. 我認為使用 Makefile 目標是最簡潔友善的方式來展示專案的功能。結果證明，當 make 和 Makefile 失敗時，它們可能會很神秘。
Tutorials are "best-effort" and often don't dwell on the rabbit-holes they create when a poor soul runs astray of the sunny path. 教學是「盡力而為」的，而且通常不會深入探討當可憐的人偏離了陽光明媚的路徑時所產生的困境。
Specify up front date and software version. I can't stress this enough. 事先指定日期和軟體版本。我再怎麼強調都不為過。
As the CADT release cycle becomes ubiquitous we're approaching a situation where many tutorials are outdated by the time you finish them. 隨著 CADT 發佈週期的普及，我們即將面臨許多教學在完成時就已過時的狀況。
I really like how clear and well laid out these rules are. It covers lots of things that I have always thought about when I write instructions in README files etc, so it's very nice to see everything neatly described/reasoned in one place. Thanks for sharing! 我非常喜歡這些規則清晰明瞭且條理分明的方式。它涵蓋了我撰寫 README 檔案等說明文件時一直以來都在思考的許多事項，因此能看到所有內容都井然有序地描述/論證在一處，真是太好了。感謝分享！
What do you think about writing a tutorial without explaining terminology, but then ask an LLM to generate some kind of terminology index that shows at hover over the terms? If I am writing a tutorial it will take me much longer to explain terminology that I assume is known before. I can see the author's points, but all things considered if I am writing "for free" I don't want to spend unneccessary time. Letting the tutorial be my words, and the terminology index be that of an LLM may be a good balance? 你覺得在撰寫教學時，不解釋術語，然後要求一個LLM產生某種類型的術語索引，在游標停留在術語上時顯示，如何？如果我正在撰寫教學，解釋我假設已知的術語將花費我更多時間。我能理解作者的觀點，但考慮到一切，如果我「免費」撰寫，我不想花費不必要的時間。讓教學是我的文字，術語索引是LLM的產物，或許是一個不錯的平衡？
This is similar to Msty's[1] "Delvify" feature that generates links for keywords in a given text, with the ability to "delve" into each highlighted topic. 這類似於 Msty[1] 的「Delvify」功能，該功能會為給定文字中的關鍵字產生連結，並能夠「深入探討」每個突出顯示的主題。
While I'm unfamiliar with how it's implemented there, I can certainly see this working with multiple rounds of prompting, and possibly some external data sources and human curation to ensure that the terminology index is actually useful to readers. 雖然我不熟悉它在那裡的實現方式，但我肯定可以看到這可以用多輪提示來實現，並且可能還有一些外部數據來源和人工策劃，以確保術語索引對讀者確實有用。
If you haven't, I highly recommend taking a look at Knuth's manuals. Even if you are completely uninterested in METAFONT or TeX, they are a delight to read and I would hold both up as a very good aspirational target for software manuals. 如果你還沒看過，我強烈建議你看看 Knuth 的手冊。即使你對 METAFONT 或 TeX 完全不感興趣，它們也讀起來令人賞心悅目，我會將它們視為軟體手冊的一個非常好的目標典範。
I am rather ambivalent about these rules. I disagree with a lot of the individual points, but I am also sure that I have probably often written bad tutorials myself where some of the rules would have clearly helped... :) 我對這些規則相當矛盾。我不同意很多個別的點，但我也很確定我可能經常自己寫出糟糕的教學，其中一些規則本來可以提供很大的幫助……:)
> 5. Make code snippets copy/pasteable > 5. 使程式碼片段可複製/貼上
I like to use the prompt to identify the language and also the user (root `#` vs. user shell `$`) to perform the action under. I advise against copying random commands off the internet especially those that run as root and may break your system (like `apt` and `--yes` together...). Of course, today, it is often assumed that you have sudo setup and then `sudo ...` is used to indicate the use of root privileges. It is an interesting convention although in my opinion this sometimes hides the actual intent. ）以執行該動作。我不建議複製網路上隨機的命令，尤其是那些以 root 身份執行的命令，這些命令可能會破壞你的系統（例如 `apt` 和 `--yes` 一起使用……）。當然，今天，通常假設你已設定 sudo，然後使用 `sudo ...` 來指示 root 權限的使用。這是一個有趣的慣例，但在我看來，這有時會隱藏實際意圖。
I prefer: 我比較喜歡：
# echo 3 > /proc/sys/vm/drop_caches
over 超過
echo 3 | sudo tee /proc/sys/vm/drop_caches
The example given in the article is exactly one where attention is required: It adds a PPA as root, thereby giving "full control" to the PPA author. Never straightout copy-paste such stuff. 文章中提供的範例正是一個需要留意的例子：它以 root 身分新增 PPA，從而賦予 PPA 作者「完全控制權」。切勿直接複製貼上此類內容。
> 6. Use long versions of command-line flags > 6. 使用命令列旗標的長格式
I am so much more used to the short versions hence I prefer `grep -RF` over `grep --dereference-recursive --fixed-strings`. Also, my go-to documentation about these commands (POSIX) doesn't even know about the long options. 我更習慣使用短格式，因此我更喜歡 `grep -RF` 而不是 `grep --dereference-recursive --fixed-strings`。此外，我常用的關於這些命令的文檔 (POSIX) 甚至不知道長選項。
I know that the advice to prefer the long options is repeated pretty often so it might just be me :) 我知道建議優先使用長選項的說法很常見，所以可能只是我個人偏好:)
> 7. Separate user-defined values from reusable logic > 7. 將使用者自訂值與可重複使用的邏輯分開
Ever followed some "enterprise-grade" software setup tutorial? Sometimes they start by assigning 20 variables to some generic values that you don't change most of the time and then go about to reference them on the next 20 pages or such making it close to impossible to know what is really going on. Also I find that for simple cases this greatly complicates the input process. 你是否曾經遵循一些「企業級」軟體設定教學？有時它們會先將 20 個變數指定給一些你大多數時間都不會更改的通用值，然後在接下來的 20 頁或更多頁面中參考它們，這使得幾乎不可能知道實際上發生了什麼。此外，我發現對於簡單的案例，這會大大複雜化輸入過程。
I think the example doesn't really show the difference because it has some variables (just not in shell syntax) in the code already like `YOUR-API-TOKEN`. Of course it is better to write `$API_TOKEN` rather than `YOUR-API-TOKEN`. I often prefer to see the example value in the example i.e. not `YOUR-API-TOKEN` but some real string (if feasible). In many cases I won't change a value in the beginning to see how far I get with a “known valid input”. Also, I often prefer to pattern-match some real value against what I have available, e.g. I have a key which I think could be the API key but if the format is totally different from the tutorial I may realize that this is an "app token" rather than "API key" and that I may need to get a different value if it fails to run with my input or such. 我認為這個範例並沒有真正顯示出差異，因為它在程式碼中已經有一些變數（只是沒有使用 shell 語法），例如 `YOUR-API-TOKEN`。當然，寫 `$API_TOKEN` 比 `YOUR-API-TOKEN` 更好。我通常更喜歡在範例中看到範例值，也就是說，不是 `YOUR-API-TOKEN`，而是某些真實字串（如果可行）。在許多情況下，我不會一開始就更改值，以查看我可以使用「已知的有效輸入」走多遠。此外，我通常更喜歡將一些真實值與我可用的值進行模式匹配，例如，我有一個我認為可能是 API 金鑰的鍵，但如果格式與教學完全不同，我可能會意識到這是一個「應用程式代碼」而不是「API 金鑰」，如果它無法使用我的輸入執行，我可能需要獲取不同的值。
> 9. Let computers evaluate conditional logic > 9. 讓電腦評估條件邏輯
If dosed correctly, I think this is good advice. I'd strongly prefer the conditional boxes from the “bad” example over the “good” monster shell script command. In my opinion a tutorial shouldn't optimize for speed of execution but rather foster the understanding by the reader. There is no help if I find this post 10 years later and it helpfully outputs “ERROR: Unsupported platform” on my Debian 16 system. If the text instructions are given as in the “bad” example, I quickly realize that all of this is outdated and I should probably try with the most recent package name (example-package2) rather than meddle with some script. 如果劑量正確，我認為這是個好建議。我強烈偏好「不良」範例中的條件方塊，而不是「良好」的巨型 shell 腳本命令。在我看來，教學不應該為了執行速度而優化，而應該促進讀者的理解。如果我在 10 年後找到這篇文章，它在我的 Debian 16 系統上很有幫助地輸出「錯誤：不支援的平台」，這對我沒有任何幫助。如果文字說明如「不良」範例中所示，我會很快意識到所有這些都已過時，我應該嘗試使用最新的套件名稱 (example-package2)，而不是去修改一些腳本。
> I am so much more used to the short versions hence I prefer `grep -RF` over `grep --dereference-recursive --fixed-strings`. Also, my go-to documentation about these commands (POSIX) doesn't even know about the long options.
I know that the advice to prefer the long options is repeated pretty often so it might just be me :) > 我更習慣使用短格式，因此我更喜歡 `grep -RF` 而不是 `grep --dereference-recursive --fixed-strings`。此外，我常用的關於這些命令的文檔 (POSIX) 甚至不知道長選項。我知道建議優先使用長選項的說法很常見，所以可能只是我個人偏好:)
It is not just you. 不只有你。
I also prefer short options for most “standard” commands (e.g. everything POSIX). I don’t see any value in educating readers in the long options of grep, or ls, or cat. 我也更喜歡大多數「標準」命令的短選項（例如，所有 POSIX 命令）。我不認為在 grep、ls 或 cat 的長選項上教育讀者有什麼價值。
OTOH using long options may be useful for less common commands, or if the commands are specific to the software the tutorial is about. 另一方面，對於較不常見的命令，或者如果命令特定於教學中涉及的軟體，使用長選項可能很有用。
Yeah, with automatic evaluation dosed correctly is key. It can quickly become a slippery slope, turning into a 100 line monstrosity supporting the most esoteric environments, like "if user is not in the sudoers group and is running offline in a dockerfile without a tty on solaris8 through pdp virtualization on apple silicon". 是的，正確使用自動評估是關鍵。它很容易變成一個滑坡，變成一個支援最深奧環境的 100 行龐然大物，例如「如果使用者不在 sudoers 群組中，並且在沒有 tty 的 dockerfile 中離線運行，通過 apple silicon 上的 pdp 虛擬化運行 solaris8」。
Some times it is better to let the user think for themselves rather than provide a "paste this magic script". If you are going to use a script, you are kindof taking away the purpose of a tutorial; to learn each individual thing step by step, not how to run another black box. 有時，讓使用者自己思考比提供「複製此神奇腳本」更好。如果你要使用腳本，你就會在某種程度上奪走了教學的目的；學習每一個單獨的步驟，而不是如何運行另一個黑盒。
You can't tell your user to "echo 'awesomecopter' | sudo tee /etc/hostname" if you may have windows users. 如果你可能有 Windows 用戶，你不能告訴你的用戶「echo 'awesomecopter' | sudo tee /etc/hostname」。
And even for purely linux user, "Good: Give the reader a bash snippet that evaluates conditional logic for them" is quite a scary wall of code for a beginner that as no idea why copy/paste that. 即使對於純粹的 Linux 用戶，「良好：給讀者一個評估條件邏輯的 bash 片段」對於一個不知道為什麼要複製/貼上這個代碼的初學者來說，也是一段相當嚇人的代碼牆。
All in all, don't confuse "giving the shortest path to a working solution" and "teaching", which both can be in a tutorial, but they have different goals and you should choose accordingly. 總而言之，不要混淆「提供通往有效解決方案的最短路徑」和「教學」，這兩種方法都可以在教學中使用，但它們有不同的目標，你應該根據情況選擇。
I think the "Teach one thing" is probably the best advice in the article, and too often ignored. I remember as a kid reading Swinnen's book to learn Python and having to understand OOP with his example using ions was a terrible experience. 我認為「一次教一件事情」可能是這篇文章中最好的建議，而且經常被忽略。我記得小時候讀 Swinnen 的書學習 Python，並且必須使用他用離子作為例子的物件導向程式設計是一個糟糕的經驗。
And if you think "well you should have known that, they teach it in school", you are missing the point. 如果你認為「好吧，你應該知道這個，學校裡有教」，你就錯過了重點。
That being said, writing an excellent tutorial takes a lot of work. Way more than a good-enough one. Choose wisely. 儘管如此，撰寫一篇優秀的教學需要大量的時間。遠比一篇夠用的教學多。明智地選擇。
I really wish more tutorial makers would do the "teach one thing". Like I dabble in gamedev, and most people who create content for it generate 45 minute to many hour long tutorials that are end to end, instead of teaching "this is how you deal with navigation" "this is how you handle movement" etc. Means people who want to learn stuff are stuck interacting with a massive block of stuff which makes extricating out the part they need and planting it in their own project wildly harder. 我真的很希望更多教學製作人能做到「一次教一件事情」。例如，我涉獵遊戲開發，大多數為其製作內容的人會製作 45 分鐘到數小時長的教學，這些教學是端到端的，而不是教「這就是你如何處理導航」、「這就是你如何處理移動」等等。這意味著想要學習東西的人被迫與大量內容互動，這使得提取他們需要的部分並將其植入他們自己的專案變得更加困難。
Yes, and then link this things to pre-requisite, and show how several of those one-things come together in a separate piece. 是的，然後將這些東西連結到先決條件，並展示這些單一事物如何在單獨的部分中結合在一起。
But again, it's a LOT of work to do that. 但同樣，這樣做需要大量的時間。
That's almost 9000 words, or 10% of the average novel size just to give beginners a good chance of success on one single topic. 這將近 9000 個字，或是一部普通小說長度的 10%，只是為了讓初學者在單一主題上獲得成功。
Between doc, tutorials, FOSS and forums, the entire software industry is just standing on a gigantic pile of billions of hours of free labor. 在文件、教學、自由及開放原始碼軟體和論壇之間，整個軟體產業只是站在數十億小時免費勞動的巨大堆積上。
I won't disagree with that. I will say pip and venv ending up being a massive chain is entirely unsurprising because Python environment management is a mess to begin with. But then there are a lot of gnarly topics that can be hard to find useful information on. 我不會不同意這一點。我會說 pip 和 venv 最終成為一個巨大的鏈條，這完全不足為奇，因為 Python 環境管理本身就是一團糟。但是還有很多棘手的問題很難找到有用的資訊。
One thing that doesn't help all this is more and more tutorials going on Youtube (I admit I've made a couple, which were topic focused) is that so many people just want an entire soup to nuts answer instead of the tools to piece together their own solution from the parts, which makes gaining traction and getting that information to people a lot harder. 讓所有這些情況更糟的是，越來越多的教學影片出現在 YouTube 上（我承認我製作了幾個，這些教學影片是主題性的），許多人只想得到一個完整的答案，而不是自己從各個部分拼湊出解決方案的工具，這使得獲得關注並將這些資訊傳達給人們變得更加困難。
But without a general change in how people look at learning I dunno what fixes that problem. 但是，如果人們對學習方式沒有普遍的改變，我不知道有什麼方法可以解決這個問題。
Diataxis gets often linked around here. It's simple, but by no means the solution to great docs. For more info, see https://idratherbewriting.com/blog/what-is-diataxis-document... Diataxis 常在此被連結。它很簡單，但絕非撰寫優良文件方案的萬靈丹。更多資訊，請見 https://idratherbewriting.com/blog/what-is-diataxis-document...
Love it - I'd add to ensure you clearly specify what version numbers you are writing for, and include a date of your writing. 喜歡它 - 我會建議確保清楚地說明您撰寫的是哪個版本號碼，並註明撰寫日期。
Things change a lot between Version 3 and 6 of something, and something written 5 years ago may no longer apply or be valid today. 版本 3 和 6 之間的差異很大，五年前撰寫的內容可能不再適用或有效。
> Make code snippets copy/pasteable > 使程式碼片段可複製/貼上
Naw, copying and pasting won't develop touch typing nor muscle memory skills. The prompt is sort of a context indicator for the command, as other comments indicate. Also if you're using one of those horrid browsers with CSS support who knows if there are characters that do not display but are included in what is copied. Security risk? Well, you started a chonky browser with a bad security record, so uh additional security risk. Also they probably should be able to type out the commands by hand at the speed of thought, or the commands should be put into a Makefile or script or done via configuration management. Making it easy to copy and paste? Well, if you want to train people to mindlessly copy-n-paste who knows what to who knows where, I guess. Doesn't sound like that would train people to engage deeply with the material. If there's a bigger code example I just put a "=> foo.lisp" link '(this is for Gemini (no, not the Google whatever nonesense (McCarthy invented AI to get money)), the modern web being too much yuck these days) so they can download the whole file. 不，複製貼上無法提升觸控打字或肌肉記憶技巧。提示是一種命令的上下文指標，正如其他評論所述。此外，如果您使用那些具有 CSS 支援的糟糕瀏覽器，誰知道是否有未顯示但包含在複製內容中的字元。安全風險？嗯，您啟動了一個安全性記錄不良的笨重瀏覽器，因此額外的安全風險。此外，他們可能應該能夠以思考的速度手動輸入命令，或者將命令放入 Makefile 或指令碼中，或透過設定管理來完成。方便複製貼上？嗯，如果您想訓練人們盲目地複製貼上到不知道哪裡，我想可以。聽起來這不會訓練人們深入參與學習內容。如果有一個更大的程式碼範例，我只是放一個 "=> foo.lisp" 連結 '(這是給 Gemini 的 (不，不是 Google 的那個無稽之談 (McCarthy 發明 AI 是為了賺錢))，現代網路現在太糟糕了)'，這樣他們就可以下載整個檔案。
> Use long versions of command-line flags > 使用命令列參數的長格式
What are these? I'm on OpenBSD. More seriously, long flags may or may not help±quick! what does --fake-super for rsync(1) do?—and taking a peek into the manual (another reason I'm on OpenBSD) is sort of a spaced repetition to refresh you on what the flag does, and maybe to scan the list of options to see if anything new jumps out at you (or, at a certain age, what you've forgotten). Close engagement with the material (howeversomuch the learner hates this, as such brain exercise uses up precious energy) is probably a good thing. 這些是什麼？我在使用 OpenBSD。更嚴肅地說，長參數可能會或可能不會有所幫助±快速！rsync(1) 的 --fake-super 參數做什麼？—查看手冊（我使用 OpenBSD 的另一個原因）是一種間隔重複，可以讓您重新學習參數的功能，並可能掃描選項列表以查看是否有任何新內容跳出來（或者，在某個年齡段，您忘記了什麼）。與學習內容的密切接觸（無論學習者多麼討厭這一點，因為這種腦力鍛鍊會消耗寶貴的能量）可能是一件好事。
(Yes, I know that OpenBSD supports but generally does not document various wacky --from-backside-of-gnu flags.) (是的，我知道 OpenBSD 支援但通常不會記錄各種古怪的 --from-backside-of-gnu 參數。)
> Teach one thing > 一次教一個東西
I am too fond of puns (and have ulterior motives, given the excess of car sitting in America, and the consequent loss of blood to the brain) to apply this in any meaningful way. 我太喜歡雙關語了（而且有不可告人的動機，鑑於美國停放著過多的汽車，以及由此造成的腦部血液損失）以任何有意義的方式應用它。
關於細節有很多好的建議！
Especially one that got my heart:
特別是其中一個打動我的：
> Some authors design their tutorials the way you’d give instructions for an origami structure. It’s a mysterious sequence of twists and folds until you get to the end, and then: wow, it’s a beautiful swan!
> 有些作者設計他們的教學就像你指導摺紙一樣。它是一連串神秘的扭轉和摺疊，直到你到達最後，然後：哇，它是一隻美麗的天鵝！
> A grand finale might be fun for origami, but it’s stressful for the reader."
> 盛大的結局對摺紙來說可能很有趣，但對讀者來說卻很令人緊張。"
Yes, a lot of tutorials are puzzle games. You need to guess other tools to install, which are obvious to the author, but not everyone.
是的，很多教學都是益智遊戲。你需要猜測要安裝哪些其他工具，這些工具對作者來說很明顯，但並非每個人都清楚。
I would add a few things:
我想補充幾點：
* Have two types of examples - minimal and the most typical (one is to show the essence without distraction, the second to serve as a practical starting point) * Always provide the full code sequence to run code; if there are any assumptions, these should be listed explicitly (e.g. "it needs Node 22"); you hinted a bit, but since many tutorials miss that, it deserves attention.
* 提供兩種範例——最小化和最典型（一種是用於顯示本質而不分心，另一種是用作實用的起點）*始終提供完整的程式碼序列以執行程式碼；如果有任何假設，這些都應明確列出（例如，「需要 Node 22」）；你稍微暗示了一下，但由於許多教學都錯過了這一點，因此值得關注。
Even better, if it is possible to combine it into one point and make it runnable. For example, for a package I had been developing, livelossplot, I made Jupyter Notebooks runnable in Colab:
更好的是，如果可以將其合併成一點並使其可執行。例如，對於我一直在開發的一個套件 livelossplot，我在 Colab 中製作了可執行的 Jupyter Notebooks：
* https://colab.research.google.com/github/stared/livelossplot... * https://colab.research.google.com/github/stared/livelossplot...
reply