今日推薦開源項目：《四根棍子 repeat-todo》
今日推薦英文原文：《Write Better Programming Tutorials》
今日推薦開源項目：《四根棍子 repeat-todo》傳送門：GitHub鏈接
推薦理由：在著名的光棍節要推薦什麼最好呢？當然是別人秀恩愛的開源項目了，項目的介紹欄里大大的寫著「I made for my wife」就證明了這一點。別說什麼程序員就不知道浪漫兩個字怎麼寫，不管是有伴的人也好沒有伴的人也罷，能夠為了他人去行動這一點就值得肯定，雖然有各種各樣不同的形式，但是根源都一樣來自於喜愛這種情感，有喜歡別人的能力，自然能找到能讓自己喜歡的人。浪漫只不過是一種更合乎氣氛的表達形式，在喜歡一個人的時候，可不要為了形式而忘記根源才好。
今日推薦英文原文：《Write Better Programming Tutorials》作者：Adam Ing
原文鏈接：https://medium.com/better-programming/write-better-programming-tutorials-5619b9cf5ca2
推薦理由：學習需要技巧，講課也需要技巧
Write Better Programming Tutorials
Share your knowledge more effectively, with more people
We publish a lot of tutorials at Better Programming. If you』ve mastered something in programming — a process, a task, a method — you can probably write a tutorial about it that other people will find useful. It could get lots of views!Say you』re working with a newly released version of a highly popular tool or framework and you learn how to do something tricky that』s not yet well documented — you have valuable knowledge to share.
Even if you』re just starting out on your programming journey, you could create something useful for other learners. In fact, basic subjects have a larger potential audience — there are always more beginners than advanced practitioners in any field.
But … to be successful you do need to know how to write an effective tutorial.
Remember:
It』s a learning resource
The style, structure, and scope of the piece should be designed to fit a learning objective. Ideally, the learning objective is clearly stated, right in the title.In this piece, I』m going to list the ingredients that go into a well-designed programming tutorial.
A Strong Introduction
You should always have an introduction.Some writers, usually with very short pieces, jump straight into the walk-through, but I think this is usually a mistake. Yes, if you』ve picked a good topic lots of your readers will know from the headline that they want to read it, but there are lots of other readers out there — people curious enough to click but who still need convincing. A short introduction before the instructions gives more people an opportunity to discover that they want to read the rest of the piece.
The introduction should cover:
- What the reader will learn from the tutorial (the learning objective)
- Whether it』s part of a larger process (is this one of a series of pieces?)
- Knowledge prerequisites (what the learner needs to know to understand this process)
- Physical prerequisites (what the learner needs to have installed on their computer)
Write Clearly and Simply
It』s always important to write clearly — but it』s absolutely crucial that a walk-through is written as clearly and simply as possible.In the introduction, you can make jokes and express a bit of your personality, but when you get to the process you should adopt a totally straightforward, transparent writing style. Transparent means the reader doesn』t even notice it. They don』t think 「what great writing」 or 「how beautifully put」 because they』re too busy taking in the information without noticing how it has been presented.
You should also stick rigorously to the steps you』re covering — this is not the place for asides or tangents. Think of it as a lesson. A good teacher might take a relaxed, informal approach in a class, but when the time comes to get down to it they』ll focus on the work and make sure the students are doing the same.
This is one of those situations where you don』t necessarily want to write the same way that you talk. 「Now go ahead and open up your terminal」 might sound winningly informal in person, but in a written tutorial, that type of casual language just slows the transmission of information and increases the chance of confusion. Just write 「Open the terminal.」 This isn』t bossy or overly formal in the right context: It』s simply neutral.
To write clearly:
- Don』t use long complicated sentences — if in doubt, split it into two
- Don』t combine steps into long paragraphs — give each step its own space
- Don』t use unnecessarily long words
- Avoid grammatical redundancies (always)
Use the Right Voice
One issue I』ve come across a few times is when a tutorial opens with something like this: 「Let』s say you are working on a project in React …」 Because they』ve presented a hypothetical situation (「Let』s say …」), the writer then starts using the conditional tense, 「You would then have to create …」 「Next, you would build it and run it.」 Ten or 20 steps later, and they』re still using 「You would」 for every instruction. This is unnecessary, and it makes things difficult to read — it introduces friction. Use the conditional tense sparingly.Instead, use the imperative form. This is what you use when you』re telling someone to do something, like 「Now open your terminal.」 Don』t worry if you don』t expect anyone to actually be following along. Writing instructions like this is the most common way to do it — therefore its expected by readers and is thus the most transparent.
Break It Up
Walk-throughs can get repetitive. Systems walk-throughs can involve scrolling through endless 「click here」 instructions, so it』s important to keep the reader engaged and oriented. If you have more than 15 or so separate steps, it』s a good idea to break it up somehow.Look for natural pauses — where you』ve finished a stage of the process, for example — to take a break from the main flow of the process. Use this moment』s pause to review what』s been achieved and what steps are left.
Use Screengrabs … But Not Too Many
For systems walk-throughs, screengrabs can be a real aid to understanding. However, they take up a lot of screen space, and if each screen is only minimally different from the last, they can make a short process walk-through difficult to navigate. It』s too easy to lose your place when you』re scrolling through numerous, similar-looking screengrabs.Save screengrabs for new screens and to highlight any easy-to-miss visual elements in the process.
Code
The most important thing to stress about code in your Better Programming tutorials is this: You should include it. It』s better to show what you』re talking about than to just link to a GitHub repository for the piece (although, please, do that as well).If you need to include very long chunks of code in the middle of a tutorial, be sure to consider how long it』ll take for the reader to digest them and how they will look on the page. A big formatted piece of code will disrupt the flow of a walk-through, so it』s a good time to take a break to reorient the reader, as discussed above.
A Final Word
In many ways, tutorials are easy to write. You』ve already done all the hard work by learning the process in the first place. If you』re an inexperienced writer, they』re a good way to get started writing because they have a clearly defined scope. Just outline exactly what task or process you』re covering and then carefully go through it, step by step. You don』t really need to argue or make a case for anything (although, as I said, making a case that the task is widely useful can increase your readership.)So, what are you waiting for? Write a tutorial today!
下載開源日報APP：https://openingsource.org/2579/
加入我們：https://openingsource.org/about/join/
關注我們：https://openingsource.org/about/love/
