Death by technical document

I often end up spending countless hours writing technical documents for projects which never see the light of day. Planning everything out to the last detail, not a single decision left up to chance yet when I go to write the code, I realise my mistake.

Viso Fox

I recently started work on Viso-Fox, a 64 bit fantasy Instruction Set Architecture (ISA).Every single decision was considered before I wrote a single line of code and knew exactly what I would have to do.

So I started working on the assembler, I realised my specification was incomplete and lacked details of how to handle strings and lacked any semblance of compile time constants.

Eventually I realised preprocessor directives would probably be the easiest way to implement compile time constants so I opted to implement my version of #define <alias> <substitution> from C. I used the syntax @meta replace <alias> <substitution> and changed strings to follow C’s norms.

But I writing a parser for C styled strings for every single edge case and then edge cases of those edge cases e.g. \ escaping but only if it has a symbol which needs to be escaped. I gave up on that very quickly, it was a toy language at the end of the day, I didn’t want to spend hours on writing an unholy regex to do the job. Not wanting to waste much more time rewriting specifications, I decided to use my own system. Instead of say \n, I had ‘@NL’ and used an extra @ to escape it but mid-implementation I realised I was wasting time.

Strings resolve to their ASCII codes e.g. A becomes 65. B becomes 66, etc. I had recently implemented a replace directive so without writing a single line of code, I realised I could define a few macros e.g. NL for ASCII’s newline code and use the already established array syntax to define strings. So I want a string to be null terminated, easy:

@array "Hello, World!", NL

Drastically reduces complexity in handling strings, just search from opening to closing quotes and if newline or end-of-file, report an error.

Blog

Another example, I refuse to pay for a server to host this blog so I needed something that was statically generated on my machine. Okay that’s easy, there’s a lot of choices of frameworks in a million different languages for that. But I didn’t want to mess around with something like Jekyll, Hugo or whatever else was popular at the time. I touch this blog maybe once a blue moon, I didn’t want to learn a whole new framework or even language to make it.

So implementing my own static blog generator it is! But that’s difficult, right? Nope, parse markdown with a Python library to generate the HTML. Create a template HTML file with ‘!blogs’ section to insert the generated HTML code into. Done.

Want to add RSS feed? Simple, a library exists for that. Just one single script to build all my blog files. No fancy pipeline, just in my .gitignore, exclude the _blogs directory which contains my build scripts, utils and markdown files.

Conclusion

Had I tried to plan out what I was going to need, wrote everything in a well structured and modular way, I would have spent an hour trying to implement it before giving Up. When I don’t have a penalty for failing, I much prefer jump into prototyping and if it needs to be refactored down the line, I’ll do a big rewrite.

P.S. I did the big rewrite, this blog now uses Hugo to generate static pages. My system was complex to automatically deploy with Cloudflare and Hugo is a few buttons to setup to deploy. I still think what I learnt by implementing my own blog platform made doing so worthwhile. I would never have learnt Hugo if I didn’t have the blog to begin with and wouldn’t have the blog if it wasn’t for my jank solution.