Introduction
This blog post focuses on ideation around building quick-start codebases that are more than just prototypes or proofs of concept. Approaches I've tried in the past (personalized template repos and tool-maintainers' guides and example repos) have some problems. I have an idea for a better solution utilizing a guided walkthrough approach with links as the primary information source.
Living the Dream was not very Dreamlike
I suspect I am not alone in my desire to go from idea to full-stack codebase in a few short hours. Rapid app creation is an illusive and (probably unwarranted) holy grail that I spend too much time trying to realize. Combine this desire with all the repos full of examples and quick-start integrations, and it's unsurprising I (and other devs like me) end up trying to write quick-start template repos and quick-start scripts.
I have spent years chasing this dream in my free time. My original idea centered around a personalized quick start tool/repo. The idea being that "all you have to do" is clone the repo, tweak some lines, and boom, new full-stack app. I even went so far as to build a script that pushed the repo to remote, generated a CICD pipeline, and even deployed the the app. All the bells and whistles! I've taken this personalized quick-start tool/repo approach multiple times, and I have achieved the goal from time to time, but it's never quite what I hoped it would be. Why is that (incompetence notwithstanding :D)? Here are some thoughts.
-
By the time I finish the quick-start tool/repo, it's already, depressingly, outdated. I don't want to spend more time maintaining my quick-start repo than I do on the one or two apps I made with it!
-
By the time I've made all the decisions involved in creating the quick-start tool, I already don't like some of those decisions. Basically, I'd immediately (and perhaps perpetually?) do it differently. I disagree with my previous self way too regularly.
-
By the time I complete my quick-start tool, I don't like it, aesthetically, ergonomically, etc. Sometimes the displeasure only comes when you can see it all in aggregate, fully integrated with itself and working as designed. Only then do the ugly horns and gotchas come out.
For the above reasons, I have moved away from the personalize quick-start approach. I then settled on the hope that I could just clone one of the infinite example repos and start building a project from one of those. The dream was I could treat example repos a bit like items in a grocery store. Walk through with my basket and pick my favorite tools, and magically smash them all together in some single personal repo to begin a project with. Well, that hope turned out even worse than the first one. In fact, I have never even achieved that dream on a project. Why is that (incompetence notwithstanding :D)?
-
Example repos make decisions that are good for demos but bad for real codebases.
-
Example repos makes decisions that require fine-tuned edits/deletions to get it to a place where you can make different code decisions. Sometimes those kinds of edits require a higher skill ceiling that what I possess for that tool, especially if it's a tool I've never tried before.
-
Example repos sometimes make no effort to be extensible.
-
Example repos are often not up-to-date or regularly maintained.
-
Example repos cannot easily be combined together, meaning that there's no real hope in "smashing together a couple repos to get things going".
A New Approach: Link-First Getting Started Guides
Guides where links are first-class citizens, prioritizing online (aka, living) tool documentation, delivered sequentially, over all else. This, I hypothesize, is the critical idea. Why?
-
Links to online docs are mostly stable (redirects if outdated, e.g.).
-
Links to online docs are almost always up-to-date with the latest version of the tool.
-
Online docs almost always care a lot about onboarding developer experience, particularly the manual setup, aka, the "integrate with an existing project" setup.
-
You are that much closer to the FAQ and Troubleshooting documentation for each tool you use, which you will inevitably consult when things don't "just work". The initial phase of a project is a lot of internet searches looking for that obscure command to integrate this tool with that other tool. A link-first guide will have the link as the first thing you see in the section.
-
Sequencing the introduction of each tool sequentially is invaluable. It guides the reader through the difficulties of integration in a generic way, while still letting the reader deviate however they choose. It is both generic, and bespoke.
You can still have example code and CLI commands in a link-first getting started guid, but they are, by design, elaborations on the links. The elaborations merely represent how things worked the last time the guide was edited.
In following a link-first guide, the reader is implicitly encouraged to check the links, and to trust the links over the elaboration content underneath them. Such a guide would then have a higher chance of maintaining relevancy until it is next updated when compared to other guide approaches like command-line-first, example-repo-first, etc.
Examples
Here is a link-first guide for Getting Started with Elixir Phoenix on Fly. It guides the reader through an Elixir, Phoenix, and LiveView full-stack todo app, deployed on Fly.
Here is a link-first guide for Getting Started with NextJS on Vercel. It guides the reader through a Next.js and Typescript frontend-only, in-memory todo app, deployed on Vercel.
Conclusion
I hope this is the endgame for my goal of moving fast with new tech ideas. It focuses almost no energy on getting the raw commands just right, and instead focuses on sequential compilation of the best resources (which are the tools' docs by the tools' maintainers).
One final point; a PS of sorts: I don't want to misrepresent this goal of a quick-start tool process. I don't personally think it's a very useful skill to have as a dev, especially when compared to the skills of maintaining a codebase over time and working well with others. But, I can't help it, I want to make a todo app in a few hours and have it go live with best(ish) practices! Maybe, if we were all collectively better at boilerplating projects, we'd have even more awesome projects out there? To that end: Here's to living the dream!
Thanks for reading :D