From b6504414344f1add87530204eefc2c94224bf503 Mon Sep 17 00:00:00 2001 From: Shu Uesugi Date: Sat, 4 Jan 2020 01:38:33 -0800 Subject: [PATCH] Get rid of highlight for the refactor article --- src/components/ContentTags/Code.tsx | 2 +- src/pages/refactor.tsx | 593 ++++++++++------------------ 2 files changed, 220 insertions(+), 375 deletions(-) diff --git a/src/components/ContentTags/Code.tsx b/src/components/ContentTags/Code.tsx index fe57b3e..09cf76c 100644 --- a/src/components/ContentTags/Code.tsx +++ b/src/components/ContentTags/Code.tsx @@ -16,7 +16,7 @@ const Code = ({ font-size: 0.95em; font-style: normal; word-break: break-word; - background: ${color ? colors(color) : colors('lightPink2')}; + background: ${color ? colors(color) : colors('lightPink1')}; ` ]} /> diff --git a/src/pages/refactor.tsx b/src/pages/refactor.tsx index 01d412a..780cc46 100644 --- a/src/pages/refactor.tsx +++ b/src/pages/refactor.tsx @@ -35,7 +35,7 @@ const techniques = [ { title: ( <> - Make code samples mobile-ready + Make code samples mobile-ready ), emojis: ['check', 'smartphone', 'check'] @@ -43,7 +43,7 @@ const techniques = [ { title: ( <> - Prefer minimal code samples + Prefer minimal code samples ), emojis: ['oneTwoThreeFour', 'singleArrow', 'one'] @@ -51,7 +51,7 @@ const techniques = [ { title: ( <> - Prefer practical code samples + Prefer practical code samples ), emojis: ['rocket', 'singleArrow', 'plane'] @@ -59,7 +59,7 @@ const techniques = [ { title: ( <> - Fail fast + Fail fast ), emojis: ['cross', 'running', 'dash'] @@ -67,8 +67,7 @@ const techniques = [ { title: ( <> - Use themes, analogies, and{' '} - quizzes + Use themes, analogies, and quizzes ), emojis: ['ghost', 'doubleArrow', 'question'] @@ -76,7 +75,7 @@ const techniques = [ { title: ( <> - Add a thoughtful touch + Add a thoughtful touch ), emojis: ['sparkles', 'heartLetter', 'sparkles'] @@ -114,22 +113,16 @@ const Page = () => ( description={<>Spaghetti code needs refactoring} />

- Similarly,{' '} - - you’ve probably also come across a coding{' '} - tutorial that’s not so reader-friendly. - {' '} - Maybe you wanted to learn a new language, library, or framework, - but the tutorial you found made you more frustrated than before. + Similarly, you’ve probably also come across a coding{' '} + tutorial that’s not so reader-friendly. Maybe you + wanted to learn a new language, library, or framework, but the + tutorial you found made you more frustrated than before.

But they can be improved. As someone who’s written many coding - tutorials, I realized that{' '} - - most coding tutorials can be refactored to be - more reader-friendly - - —just like refactoring code. + tutorials, I realized that most coding tutorials can be{' '} + refactored to be more reader-friendly—just like + refactoring code.

( />

However, while many programmers have written guidelines on how to - refactor code,{' '} - - guidelines on how to refactor coding tutorials are rare. - {' '} + refactor code, guidelines on how to refactor coding tutorials are + rare.

So, in this article, I’ll share six opinionated @@ -183,13 +174,9 @@ const Page = () => ( content: ( <>

- Even if you’ve never written a coding tutorial,{' '} - - you might know someone who has (maybe one of your Twitter - followers) - - . I’d appreciate it if you could share this article with them. - You can{' '} + Even if you’ve never written a coding tutorial, you might know + someone who has (maybe one of your Twitter followers). I’d + appreciate it if you could share this article with them. You can{' '} (

Did you notice that the above code is{' '} - formatted to fit on a small screen?{' '} - - Because each line length is short (max 31 chars), - {' '} - you can read it without side-scrolling on most phones. + formatted to fit on a small screen? Because each line + length is short (max 31 chars), you can read it without + side-scrolling on most phones.

If the above code was formatted in a single line like below @@ -239,9 +224,7 @@ const Page = () => ( Max line length: {' '} 79 characters
- - Line is too long; must scroll or wrap on a phone - + Line is too long; must scroll or wrap on a phone } /> @@ -273,28 +256,19 @@ const Page = () => ( Max line length: {' '} 72 characters
- - Line is too long; must scroll or wrap on a phone - + Line is too long; must scroll or wrap on a phone } />

So, here’s my first refactoring tip:{' '} - - - Make code samples in your tutorials mobile-ready. - - -

-

- You can ensure this by keeping line length short.{' '} - I try to keep it under about 50 characters{' '} - (at 14px font size). I use{' '} - - Prettier - {' '} - with custom printWidth to automate this (my{' '} + Make code samples in your tutorials mobile-ready. +

+

+ You can ensure this by keeping line length short. I try + to keep it under about 50 characters (at 14px font size). + I use Prettier with custom{' '} + printWidth to automate this (my{' '} .prettierrc is{' '} here @@ -308,37 +282,30 @@ const Page = () => (

Here are some other techniques:

- Why is this necessary?{' '} - - Because many people actually read coding tutorials on - their phones. - {' '} + Why is this necessary? Because many people{' '} + actually read coding tutorials on their phones.

You might be tempted to assume that your readers will read (and follow along) your coding tutorial on a computer.{' '} - But that’s a bad assumption. + But that’s a bad assumption.

In the past, I’ve used Google Analytics to track desktop vs mobile @@ -347,38 +314,30 @@ const Page = () => ( from a mobile device.

- This is because{' '} - - many people discover coding tutorials while - using a phone to browse Twitter, mailing lists, and online - forums. - + This is because many people discover coding tutorials + while using a phone to browse Twitter, mailing lists, and online + forums.

- Many people discover coding tutorials while - using a phone to browse Twitter, etc. + Many people discover coding tutorials while using a + phone to browse Twitter, etc. } />

- That’s why mobile reading experience is important.{' '} - - If you can easily read all the code samples on a phone, you - might be able to finish the tutorial without pulling out your - computer. - {' '} - Sometimes you need to follow along on your computer to fully - understand the content, but that’s not always the case. + That’s why mobile reading experience is important. If you can + easily read all the code samples on a phone, you might be able to + finish the tutorial without pulling out your computer. Sometimes + you need to follow along on your computer to fully understand the + content, but that’s not always the case.

- The bottom line:{' '} - - Assume that people will discover your coding tutorial on their - phone and try to deliver the best possible first impression. - + The bottom line: Assume that people will discover + your coding tutorial on their phone and try to deliver the best + possible first impression.

), @@ -387,12 +346,11 @@ const Page = () => ( <>

Video tutorials: What I’ve said so far applies - to text-based tutorials.{' '} - For video tutorials (screencasts), it’d - be ideal if the fonts are large enough to be legible on a phone - (in landscape mode). I like watching coding tutorials on - YouTube, but sometimes the fonts are too small when viewed on my - phone. + to text-based tutorials. For{' '} + video tutorials (screencasts), it’d be ideal if the + fonts are large enough to be legible on a phone (in landscape + mode). I like watching coding tutorials on YouTube, but + sometimes the fonts are too small when viewed on my phone.

) @@ -410,20 +368,14 @@ const Page = () => ( TypeScript handbook {' '} (which is written in a way that’s both a tutorial and - documentation). And the handbook{' '} - - uses this code to explain how to use{' '} - a particular TypeScript keyword/operator. - + documentation). And the handbook uses this code to explain how to + use a particular TypeScript keyword/operator.

- Question:{' '} - - Can you tell which keyword/operator is being explained through - this code? - {' '} - Hint: It is one of the keywords/operators used in the code. (You - don’t need to know TypeScript—just guess!) + Question: Can you tell which keyword/operator is + being explained through this code? Hint: It is one of the + keywords/operators used in the code. (You don’t need to know + TypeScript—just guess!)

@@ -431,14 +383,11 @@ const Page = () => ( TypeScript handbook {' '} - uses the above code to explain{' '} - - how to use the{' '} - - “&” operator - {' '} - in TypeScript. - + uses the above code to explain how to use the{' '} + + “&” operator + {' '} + in TypeScript.

(

But it’s hard to tell! If you look at the code again, only{' '} - the highlighted part + the highlighted part {' '} - below is related to the{' '} - - “&” operator - - . There are too many other keywords that are just noise (e.g.{' '} + below is related to the “&” operator. There are + too many other keywords that are just noise (e.g.{' '} Partial<>, hasOwnProperty,{' '} as, constructor, public,{' '} interface, void, implements @@ -481,7 +427,7 @@ const Page = () => ( <> Only{' '} - the highlighted part + the highlighted part {' '} is related to{' '} @@ -493,29 +439,20 @@ const Page = () => ( } />

- So, in my opinion,{' '} - - the above code sample is NOT a great way - {' '} - to explain how to use the{' '} - - “&” operator - {' '} - in TypeScript. It does show a few places where the “ - &” operator can be used, which is good, but it - could have been done without adding so much noise. + So, in my opinion, the above code sample is{' '} + NOT a great way to explain how to use the “ + &” operator in TypeScript. It does show a few + places where the “&” operator can be used, which + is good, but it could have been done without adding so much noise.

If I were to explain how the “&” operator works - in TypeScript,{' '} - - I’d refactor the earlier code as follows - - —it basically does the same thing in a simpler way. You don’t need - to understand TypeScript to know that this is more minimal and - focused on explaining how to use the “&” - operator. The amount it takes to understand this code is also much - shorter. + in TypeScript, I’d refactor the earlier code as + follows—it basically does the same thing in a simpler way. You + don’t need to understand TypeScript to know that this is more + minimal and focused on explaining how to use the “ + &” operator. The amount it takes to understand + this code is also much shorter.

( What I want to say is: Prefer minimal code samples, at least initially. {' '} - - If you’re trying to teach a new concept (let’s call this “ - X”), just focus on X in the - code sample and don’t add too much extra stuff. - {' '} - Add extra stuff only (1) after you showed a simple example and (2) - when it really helps the reader’s understanding. + If you’re trying to teach a new concept (let’s call this “ + X”), just focus on X in the code + sample and don’t add too much extra stuff. Add extra stuff only + (1) after you showed a simple example and (2) when it{' '} + really helps the reader’s understanding.

Minimal reproducible example: When you ask a question on StackOverflow or file an issue on GitHub, you’re often - asked to create a{' '} - minimal reproducible example. Your code - needs to be as small as possible, such that it is just sufficient - to demonstrate the problem, but without any additional complexity - ( + asked to create a minimal reproducible example. Your code needs to + be as small as possible, such that it is just sufficient to + demonstrate the problem, but without any additional complexity ( Wikipedia’s definition @@ -563,10 +496,10 @@ const Page = () => (

You should use the same principle when writing code samples for your tutorials. Ask yourself:{' '} - + Can I make this code sample more minimal while maintaining the learning experience? - +

), @@ -577,11 +510,10 @@ const Page = () => ( Tutorials vs Documentations: There is a difference in what should code samples be like for{' '} tutorials vs documentations.{' '} - Tutorials are for{' '} - learning, so it’s often better to keep - code samples minimal to reduce confusion (except for advanced - topics). Documentations are{' '} - references, so it’s often better to have + Tutorials are for learning, so it’s + often better to keep code samples minimal to reduce confusion + (except for advanced topics). Documentations{' '} + are references, so it’s often better to have comprehensive code samples.

@@ -606,12 +538,9 @@ const Page = () => ( TypeScript handbook {' '} - (right after the example we showed earlier). And the handbook{' '} - - uses this code to explain how to use the{' '} - union operator in TypeScript, - {' '} - which is the{' '} + (right after the example we showed earlier). And the handbook uses + this code to explain how to use the{' '} + union operator in TypeScript, which is the{' '} “|” {' '} @@ -629,17 +558,14 @@ const Page = () => ( } />

- In TypeScript,{' '} - - you can write{' '} - - number | string - {' '} - to specify that a parameter can either be number OR{' '} - string - - . So in this case, the second padding parameter can - be either number or string. + In TypeScript, you can write{' '} + + number | string + {' '} + to specify that a parameter can either be number OR{' '} + string. So in this case, the second{' '} + padding parameter can be either number{' '} + or string.

    @@ -660,15 +586,12 @@ const Page = () => ( } />

    - Now, a question for you:{' '} - - Is padLeft() a good example to explain how{' '} - the{' '} - - “|” - {' '} - operator works in TypeScript? - + Now, a question for you: Is{' '} + padLeft() a good example to explain how the{' '} + + “|” + {' '} + operator works in TypeScript?

    (

    Take a look below and ask yourself:{' '} - + Would you EVER use padLeft() for the case where the second parameter is string? - +

    ( />

    You probably would not. It just does simple - string concatenation in reverse.{' '} - - You probably would just use other standard ways to concatenate - strings, such as 'Jim: ' + 'Hello World'. - {' '} - There’s no good reason why padLeft() should support - the second string parameter. + string concatenation in reverse. You probably would just use other + standard ways to concatenate strings, such as{' '} + 'Jim: ' + 'Hello World'. There’s no good reason why{' '} + padLeft() should support the second string parameter.

    The bottom line:{' '} padLeft(value, padding) is useful if{' '} - padding is number but is{' '} - - pretty useless if padding is string. - {' '} - So setting padding’s type as{' '} - number | string is not useful—it could just be{' '} - number. That’s why this is NOT a good example. + padding is number but is pretty useless + if padding is string. So setting{' '} + padding’s type as number | string is not + useful—it could just be number. That’s why this is + NOT a good example.

    So, here’s my third refactoring tip:{' '} - Prefer practical code samples.{' '} - Avoid showing code no one would write. If - you’re trying to teach a new concept (let’s call this “ - X”),{' '} - - come up with a practical code sample where{' '} - X is actually useful in solving the - problem. - -

    -

    - By showing a practical example,{' '} - - readers will understand why X is worth - learning. - {' '} - If you show them a useless example, they’d think:{' '} + Prefer practical code samples. Avoid showing code + no one would write. If you’re trying to teach a new concept (let’s + call this “X”), come up with a practical{' '} + code sample where X is actually useful + in solving the problem. +

    +

    + By showing a practical example, readers will understand why{' '} + X is worth learning. If you show them a useless + example, they’d think:{' '} “What’s the point of learning X?” @@ -782,20 +693,18 @@ const Page = () => ( styled-system {' '} - work. In other words, it’s a practical example.{' '} - - It actually makes sense to have the parameter be either{' '} - number or string, - {' '} - unlike the previous example. + work. In other words, it’s a practical example. + It actually makes sense to have the parameter be either{' '} + number or string, unlike the previous + example.

    To summarize, always ask yourself:{' '} - + Is my code sample practical? Would anyone ever write code like this? - +

    ), @@ -803,12 +712,10 @@ const Page = () => ( content: ( <>

    - padLeft() could have been - useful if you could pass both a{' '} - number AND a{' '} - string, and have it repeat the - string the specified number of times (see below). But that’s not - what was in the handbook. + padLeft() could have been useful if you + could pass both a number AND a string, + and have it repeat the string the specified number of times (see + below). But that’s not what was in the handbook.

    (

    Furthermore, it’s more effective if you fail fast - .{' '} - - Try to show a failing scenario{' '} - as early as possible in your article. - {' '} - By doing so, you’ll be able to capture your reader’s attention - right off the bat. + . Try to show a failing scenario{' '} + as early as possible in your article. By doing + so, you’ll be able to capture your reader’s attention right off + the bat.

    For example, on{' '} @@ -869,17 +773,11 @@ const Page = () => (

    Here’s a simple technique you can use. If you want to teach a new - concept (let’s call this “X”),{' '} - - start with a concrete scenario where things fail or - aren’t ideal when you don’t use X. - {' '} - Then,{' '} - - use X to solve the problem. - {' '} - Your readers will pay more attention and also understand why{' '} - X is worth learning. + concept (let’s call this “X”), start with a{' '} + concrete scenario where things fail or aren’t ideal when + you don’t use X. Then, use X to + solve the problem. Your readers will pay more attention and also + understand why X is worth learning.

    I used this technique on{' '} @@ -895,11 +793,9 @@ const Page = () => ( In a way, this is similar to{' '} test driven development (TDD). In TDD, you write a failing test first, and after you watch it fail, you try to make - it pass. Similarly, in a coding tutorial,{' '} - - it’s more effective if you show a failing example first and have - the readers watch it fail. - + it pass. Similarly, in a coding tutorial, it’s more effective if + you show a failing example first and have the readers watch it + fail.

    ( It’s tempting to be lazy and skip writing a failing test in TDD. Similarly, when writing a coding tutorial, it’s tempting to skip showing a failing example and just start with a successful - example. But resist this temptation— - failure is your friend in expository - writing. + example. But resist this temptation—failure is your friend in + expository writing.

    The bottom line:{' '} - + Double-check to see where the first failing example appears in your tutorial. If it’s missing, add one near the beginning. - +

    ), @@ -932,9 +827,9 @@ const Page = () => ( <>

    Fail unexpectedly: It’s also more effective if - the failure is surprising. Trick your - reader into thinking that a code sample would work - perfectly…then make it fail. Make your readers think,{' '} + the failure is surprising. Trick your reader into + thinking that a code sample would work perfectly…then make it + fail. Make your readers think,{' '} “WTF? How come it doesn’t work?”—and they’ll be more curious. Unexpected failure = more memorable learning experience. @@ -954,16 +849,12 @@ const Page = () => (

    - First,{' '} - - use themes: - {' '} - - If your tutorial doesn’t have an underlying{' '} - theme that ties together your examples, try to - add one - - . Having an extremely simple theme is better than having no theme. + First, use themes: + If your tutorial doesn’t have an underlying + theme + {' '} + that ties together your examples, try to add one. Having an + extremely simple theme is better than having no theme.

    For example, on{' '} @@ -973,18 +864,14 @@ const Page = () => ( (types, read-only properties, mapped types, array types, literal types, intersection types, union types, and optional properties) - . Instead of covering each topic separately,{' '} - - I use a simple theme of building a todo app to - explain all those 8 topics. - {' '} - The idea is to add features to a todo app one by one using + . Instead of covering each topic separately, I use a simple theme + of building a todo app to explain all those 8 + topics. The idea is to add features to a todo app one by one using TypeScript.

    - First, you implement the “toggle todo”{' '} - feature of a todo app. This lets you check and uncheck the - checkboxes—try it below! + First, you implement the “toggle todo” feature of a todo app. This + lets you check and uncheck the checkboxes—try it below!

    ↑ Check and uncheck the checkboxes!} @@ -1000,15 +887,11 @@ const Page = () => (

    After that, you implement the{' '} - “mark all as completed” feature, which - checks all the checkboxes at once. + “mark all as completed” feature, which checks all + the checkboxes at once.

    - ↑ Try pressing “Mark all as completed” - - } + promptArrowText={<>↑ Try pressing “Mark all as completed”} defaultData={[ { id: 1, text: 'First todo', done: false }, { id: 2, text: 'Second todo', done: false } @@ -1023,22 +906,16 @@ const Page = () => ( TypeScript.

    - You get the idea.{' '} - - When I want to teach many concepts at once, I prefer to use{' '} - a specific theme to explain them all—in this - case, building a todo app. - {' '} - By doing so, readers won’t have to do as much context switching in - their head. + You get the idea. When I want to teach many concepts at once, I + prefer to use a specific theme to explain them + all—in this case, building a todo app. By doing so, readers won’t + have to do as much context switching in their head.

    Second,{' '} - - use analogies to explain new concepts. - {' '} - Tie a new concept with the concept your reader already knows. + use analogies to explain new concepts. Tie a new + concept with the concept your reader already knows.

    By the way, did you notice that I used several analogies in this @@ -1046,26 +923,21 @@ const Page = () => (

      - I compared refactoring code with{' '} - refactoring a coding tutorial. + I compared refactoring code with{' '} + refactoring a coding tutorial. - I compared minimum reproducible examples{' '} - with minimal code samples. + I compared minimum reproducible examples with{' '} + minimal code samples. - I compared TDD with{' '} - using failing examples. + I compared TDD with using failing examples.

    - Note:{' '} - - If your analogy isn’t perfect, use it anyway but say “it’s not a - perfect comparison.” - {' '} - It would still help your reader memorize the concept. I did this - on my{' '} + Note: If your analogy isn’t perfect, use it + anyway but say “it’s not a perfect comparison.” It would + still help your reader memorize the concept. I did this on my{' '} TypeScript tutorial when I compare TypeScript’s type-checking feature with unit tests. Here’s what I wrote: @@ -1073,31 +945,22 @@ const Page = () => (

    So in a sense, TypeScript’s types act as lightweight unit tests - that run every time you save (compile) the code. ( - - Of course, this analogy is a simplification. You should still - write tests in TypeScript! - - ) + that run every time you save (compile) the code. (Of course, + this analogy is a simplification. You should still write tests + in TypeScript!)

    - Finally,{' '} - - use quizzes - {' '} - to make your readers pause, think, and be engaged. + Finally, use quizzes to + make your readers pause, think, and be engaged.

    - In your tutorial,{' '} - - count how many times you ask simple questions, such as{' '} - “what would happen if you do X?” or{' '} - “what’s wrong with the following code?” - - . Even non-interactive, simple yes-no quizzes are better than - having no quiz! + In your tutorial, count how many times you ask simple questions, + such as “what would happen if you do X?” or{' '} + “what’s wrong with the following code?”. Even + non-interactive, simple yes-no quizzes are better than having no + quiz!

    ) @@ -1118,9 +981,8 @@ const Page = () => ( {' '} Highlight or{' '} bold important words/lines so your readers know - what to pay attention to. You can also{' '} - add a comment next to the emphasized - words/lines for more clarity. + what to pay attention to. You can also add a comment next + to the emphasized words/lines for more clarity.

    ( I spent a year traveling the world in 2018 - , and one thing I learned is that{' '} - - so many people in the world can speak some English, but many - don’t speak English well - - . Globally,{' '} + , and one thing I learned is that so many people in the world can + speak some English, but many don’t speak English{' '} + well. Globally,{' '} there are 3x as many non-native English speakers as native English speakers @@ -1195,12 +1054,9 @@ const Page = () => ( description={<>Use simple English} />

    - Also: If you’re living in the US,{' '} - - avoid cultural references and humor that only people familiar - with American culture would understand - - . Always ask yourself:{' '} + Also: If you’re living in the US, avoid cultural references and + humor that only people familiar with American culture would + understand. Always ask yourself:{' '} “Would someone living far, far away from where I live understand what I’m writing?” @@ -1223,9 +1079,7 @@ const Page = () => (

    So if possible,{' '} - - let your reader know what steps you’re skipping - + let your reader know what steps you’re skipping —by doing so, they won’t be as confused, and they can Google how to do the missing steps if necessary.

    @@ -1242,12 +1096,8 @@ const Page = () => ( } />

    - Also,{' '} - - if your tutorial requires some prerequisite knowledge, - explicitly list them - - . For example,{' '} + Also, if your tutorial requires some prerequisite knowledge, + explicitly list them. For example,{' '} my TypeScript generics tutorial {' '} @@ -1256,12 +1106,8 @@ const Page = () => ( unfamiliar with them.

    - Finally,{' '} - - check if you’re using a convention that newcomers may not know - about. - {' '} - On{' '} + Finally, check if you’re using a convention that newcomers may not + know about. On{' '} my TypeScript generics tutorial @@ -1279,11 +1125,11 @@ const Page = () => (

    Finally, when things get hard, be encouraging.{' '} Use phrases like:{' '} - + “This topic is harder than other topics we’ve covered. Don’t worry if you don’t get immediately—just keep reading and you’ll get it eventually!” - {' '} + {' '} A little touch of empathy can go a long way.{' '}

    @@ -1305,8 +1151,8 @@ const Page = () => (     create-react-app - , etc) that many beginners/newcomers use. - Here’s his quote: + , etc) that many beginners/newcomers use. Here’s his + quote:

    @@ -1353,8 +1199,7 @@ const Page = () => ( > click here to tweet this article. {' '} - Also, I’d love it if you could like or{' '} - retweet the tweet below! ↓ + Also, I’d love it if you could like or retweet the tweet below! ↓