TLDR: How author forgot his own code, ended up wasting time and learned importance of documenting the code.
As you don't know, I am developing yet another analytics service Easyanalytics that is a paid alternative to a free service provided by a trillion-dollar company. It is a no-brainer that all I need to do is develop a subpar service with fewer features, and customers will come flocking to it 😉, right?
How I ended up writing my own theme
Now, I am not a novice when it comes to indie hacking; I have all the wisdom from my inordinate time spent on Hacker News, Twitter, and Reddit. I truly believe in the "not invented here" philosophy, meaning if it is not invented by me, it must be good. So then, how did I fall into the trap of creating my own theme with a landing page, blog, and documentation?
Good intentions
I decided that I would not waste my time on anything that is not core to my product. Instead, I will waste my time in searching for that perfect unicorn theme that will fulfill all my needs: a beautiful landing page, searchable docs with a table of contents for easy navigation, a sidebar with all the topics on one side, which looks good on both mobile and desktop, a blog with a TOC, related blogs, easy social sharing that is SEO-optimized with Twitter cards, Facebook's OG, Google's schema, and support for sitemap, robots, localization, and 404, etc. I hope I am not forgetting anything important. If I missed something, please inform me so that I can restart my search again 🫤!
Leverage
I am also big on leverage. You see, leverage helps you get a compounding effect; it's just like option trading, where I lost all my money, but that's a different story. So, since I have some experience with Golang, I chose Hugo as the static site generator (SSG). Choosing it had a twin advantage: in case I wanted to customize something in Hugo, I could leverage my Golang skills. Additionally, since it uses Golang template syntax for its themes, I don't need to learn another syntax for templating if I want to customize something in the Hugo theme.
After going through all the themes listed in Hugo Themes multiple times, I chose the Doks theme as it was the only theme that included docs, landing page, and blog features in Hugo. Now, I just needed to customize the landing page a bit, and I would be ready to go. I created a mockup of my landing page, and all I wanted was to replicate it in Hugo with the Doks theme. However, I kept going through Hugo docs and the Doks theme without accomplishing anything. Hugo has organized its documentation like a maze; while it's fun to navigate if you want to kill time, it is not exactly helpful when you want to quickly do something that you can already achieve using just HTML and CSS. The last straw was the Doks theme pulling the rug out from under my feet by changing its architecture. Now, I had to either stick to the older version or relearn how to create my mockup with the new architecture!
So, I did what any sane person would do in this situation. No, I did not stick to the older version and just release my site; I rolled up my sleeves and decided I needed to create my own theme. You can consider it an investment; who knows how many products I will be launching in the foreseeable future? This is like a basic requirement to launch any product, so I created my own theme. I implemented everything from the blog to docs to search in docs before I had a single blog post or documentation. I tested everything, committed the code, and deleted the content I was using to test the functionality. Finally, something was accomplished 🥵. It looks worse than the older Doks theme or, for that matter, other half-arsed themes, but at least I will be able to move quickly in the future.
I went back to working on Easyanalytics, and three months later, after implementing a few more features, I decided to spend some time on documentation, only to find out that the search is not working. Now, I vaguely remembered implementing it but completely forgot what needs to be done for it to work. I implemented it using the excellent FlexSearch library but generated the index used for searching using a data template and stored it separately to avoid unnecessary loading time. Unfortunately, I forgot the settings that need to be done for generating the index. I ended up going through my template code to re-understand how it works and figure out the settings needed to generate the index. I wasted the entire day because I neither documented it anywhere nor put it in the commit message, which would have made my life easier.
Lesson Learned
Please document things as you go along; don't be like me. I still don't have formal documentation; however, as a compromise, I am writing more descriptive GitHub messages now so that it is at least documented somewhere
PS: I am wondering if I should write a tutorial on using Hugo with a top-down approach. Hugo's documentation is convoluted, and other tutorials that I have seen also take a similar approach of explaining how things are organized in Hugo rather than telling you how to do X in Hugo.