You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: src/content/blog/2025-10-08-lets-talk-sample-apps.md
+58-1Lines changed: 58 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,6 +2,7 @@
2
2
date: "2025-10-08T19:44:48+08:00"
3
3
slug: "lets-talk-sample-apps"
4
4
og_image: /images/posts/tag-ure-it.jpg
5
+
hascodepen: true
5
6
tags:
6
7
- javascript
7
8
- devlife
@@ -10,7 +11,7 @@ title: "Let's talk sample apps"
10
11
draft: true
11
12
---
12
13
13
-
I'm back in the Developer Relations profession. But after going through the [migration](/blog/migrating-from-hugo-to-astro) last weekend, it occurred to me that some part of my current job was something that I have been doing over the years I've had this blog. And that is, explaining to others how something is done and how things work.
14
+
I'm back in the Developer Relations profession. But after going through the [migration](/blog/migrating-from-hugo-to-astro) last weekend, it occurred to me that some part of my current job was something that I had already been doing over the years I've had this blog. And that is, explaining to others how something is done and how things work.
14
15
15
16
My only 2 developer relations jobs were at companies that provided SDKs as products to developers (among other things they do to make revenue). And so it was important to show developers how our SDKs were used and what you could do with them. This meant that I needed to know these SDKs really well, especially all the bits that don't work very well.
16
17
@@ -25,3 +26,59 @@ What is the point of a sample application? Well, for my context, I would broadly
25
26
Such applications are meant to guide a developer on how to implement something and hopefully they can apply what they learned into their own applications
26
27
2.**Showcase sample applications**
27
28
Such applications are meant to show what a particular technology makes possible
29
+
30
+
Based on these categorisations, I would say that learning sample apps would end up being flatter in project structure, since the main purpose is to let developers understand how a particular feature is implemented. You wouldn't spend time optimising and modularising everything to be "production-ready", whatever that means.
31
+
32
+
Personally I think showcase apps can just go wild. I mean, I used to work in [advertising](/resume/#nurun) where sometimes, even things meant for "production" felt like they were just showcase apps held together by duct tape and the hopes and prayers of the account manager. If you know what I mean.
33
+
34
+
The rest of this post is focused on learning sample apps. Showcase apps can do whatever they want.
35
+
36
+
## Decisions, decisions…
37
+
38
+
When I was young and stupid, I was rather opinionated about the "best" way to do things. Now that I'm old and stupid, I'm much less opinionated, and hopefully less stupid as well. The best way to do things is extremely contextual, so the only guiding principle I go by is to assess the situation you're in.
39
+
40
+
Anywayz, I had been thinking about the best way to structure sample web applications for the purpose of learning. And wanted to keep a record of my thought process.
41
+
42
+
First and foremost, what is the specific thing you're trying to explain, and what is its **native environment**? For example, if I'm trying to teach someone how Flexbox works, then I would consider the native environment CSS. If I'm trying to teach someone how to use a particular Node.js SDK, then I would consider the native environment JavaScript or Typescript, you get the picture.
43
+
44
+
Next thing I took into consideration was the **habits and preferences** of the audience I was trying to reach. If you're building in the AI space, odds are the preferred language is going to be Python. A lot of developers building applications on the blockchain seem to default to React and (sadly) Tailwind. I'm still not a big fan of Tailwind but I can see its use-cases.
45
+
46
+
Also, would there be more sample apps **related to the same topic**. Or are they **individual snowflakes**? If the sample apps are part of a larger theme, do you want to have unified visuals for UI components? For example, if you're building developer documentation for a suite of product SDKs, maybe your sample apps all follow a similar structure and use the same libraries.
47
+
48
+
Again, there are no hard and fast rules, but a series of trade-offs between how much effort you can afford versus the range of audiences you are trying to reach, I suppose. In a world where unicorns poop rainbows, you could show your developer audience every flavour of how something is done, but sadly, we live here.
49
+
50
+
## Highlight the critical code
51
+
52
+
As a bilingual speaker, I honestly wanted by heading for this section to be "讲重点" but I didn't have the language skills to translate that concisely while keeping the gist right.
53
+
54
+
### CSS
55
+
56
+
I've built quite a few demos on CodePen as well as standalone sites over the years. A lot of them are about CSS (86 posts on this blog so far). Most of the demos need some form of "unrelated" code just to make the demo look decent so people don't get so distracted by the lack of styling they miss the point altogether.
57
+
58
+
For those, I've mostly grouped those styles at the bottom (generally safe cascading since they're not touching the actual elements for the demo), and use a comment to indicate they are layout styles. This seems to be a relatively common approach based on what I've seen.
<span>See the Pen <ahref="https://codepen.io/huijing/pen/RwvzoRp">
62
+
View Transitions API</a> by Chen Hui Jing (<ahref="https://codepen.io/huijing">@huijing</a>)
63
+
on <ahref="https://codepen.io">CodePen</a>.</span>
64
+
</p>
65
+
66
+
Another approach that came to mind was to have the unrelated styles as inline styles on the HTML elements themselves, and leave ONLY the relevant CSS in the stylesheet. That way there is no ambiguity and everything in the CSS file is relevant. I feel this approach could make it easier to immediately parse the CSS that is doing the actual work.
67
+
68
+
I'm still in two minds on whether to extend this to the actual element being styled itself. Say if I'm explaining Flexbox, and I put the border style for the element inline instead, you know? [Share your thoughts](https://bsky.app/profile/huijing.bsky.social) on this with me, if you have any.
69
+
70
+
### JavaScript
71
+
72
+
For JavaScript it might be trickier. But I have done 2 (or more) separate JavaScript files, where one only contains the relevant logic and the other ones handle everything else to make the website work. With the [module syntax](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) now pretty much the norm, there are so many levels of abstraction possible, and this is one area I feel warrants a bit more deliberate thought.
73
+
74
+
When writing tutorials around such sample apps, I always ponder how copy-pastable my code is. Ideally, you're really not supposed to wholesale copy and paste a sample app code into your own application but you know and I know and your cat knows that people tend to do that. I lean more heavily towards leaving the responsibility of modularisation up to the developer themselves.
75
+
76
+
Or even for frameworks, like React. If you look at the average React project, it's components all the way down, which is sort of the right way to do things. But I've personally spent a lot of time digging through components like a forensics team trying to find a dead body just to locate where the logic lies.
77
+
78
+
For a learning sample app, I would propose keeping all UI components as dumb as possible, then dump all the relevant logic into a big-ass custom hook. Is this best practice? Probably not, but it sure makes it easier to find feature implementation code. Generally, I'm thinking along the lines of getting the framework code out of the way as much as possible.
79
+
80
+
## Wrapping up
81
+
82
+
If you made it this far, thank you reading the words that I wrote. I'm under the impression that most people don't actually read these days. But hey, what do I know? I'm still amazed that this blog has existed for more than 11 years. A couple of years ago, I too had fallen into the category of people who Googled how to do something and landed on their own blog post.
0 commit comments