Blog: manifest

Blogs are uniquely useful

Projects accumulate text in various places, each of which are specialized for different writing styles. Version control logs are for listing changes: why they were made and their effects. Since logs are often viewed in batches, their length is limited and details are sparse. Code comments are more detailed, but must also be brief since they are referenced quick and often. Blogs have no such limitations. Information skipped elsewhere can be elaborated upon freely. Blogs can provide background for suspiciously uncomplicated changes. They're a good place to talk about anything at length when most of computing calls for as little as possible to get the job done.

Blogs are also special because they are external to the project. The audience is relatively unacquainted with the software compared to the consumers of other types of documentation. Preliminary concepts may need a reintroduction. Any new ideas should be explained from the perspective of a layperson. Shifting to an outside audience can reveal assumptions and tacitly endured issues. Engaging the new user experience is usually a normal part of testing. Still, it's easy to think something is simple and works right if you authored it. Difficulty writing up an algorithm indicates over-engineering. Even something easy to get down on paper might not look right, presenting an opportunity for revision. At the end of the day, only an understandable project is usable.

Reflection doesn't have to happen at the end of a project. Blogs written during development inform development. Designing in plain English produces clearer ideas. Organizing components is simpler in a single document than spread across a file system. Patterns are easier to spot in one place. Then those patterns can be refined and abstracted. It's always a good time to start writing about a project. Writing takes thinking.

If nobody blogs it, did it even happen?

A project which is only documented internally could disappear forever with one rm -fr. Blogging is the best way to keep its memory alive, even if something happens. Small projects, neat scripts, and difficult tasks are at enhanced risk of vanishing. Failures should also be recorded lest they become doomed to repetition. A single changelog line might be the result of hours of frustration. Everything is a learning opportunity. One can only stand to know more by keeping thorough records.

Detailed logs serve other purposes too. They lessen the strain caused by breaks between development periods. Even a few weeks can be enough to forget what's going on if nothing is written down. Start logs early — early enough to capture the excitement from the initial idea. Well-written blog posts inspire other forms of documentation. Posts not about projects will be notes for the future. Anything else will be nice to look back on.

Project timeline

I wanted to write my webpages in Markdown for a while. I need some text and don't need any fancy graphics. I like how natural it feels to write Markdown. I also use it on GitHub. So the choice wasn't hard, but getting it to work took a few tries. First, I tried using njs and some npm package. Then something broke in the upstream njs package, so I reverted my webpages to plain HTML.

In early May 2024, I reimplemented my main web-server in Go. I published that version a few days later. I finished the blog page and blog post template, but then I got busy. My changes hung uncommitted on my laptop until I found time. Eventually I got things how I wanted them, added tasks to my to-do list, and committed everything.

Finally, in mid-July, I published my working blog and its first post — this one! Writing the post between work took way longer than the Go server. Organizing why I wanted to start a blog was important, and I hope this post can serve as an informal policy for future entries.

tl;dr

I want to make a blog to document my development in one place, reflect on what I'm doing, hopefully improve, and keep track of things that don't necessarily make it anywhere else. And I'm writing my webpages in Markdown now.