In the previous post, I briefly recap the effort I have made to build a personal website. As you can tell from my previous work, I’m super into Sphinx-doc tool and I’m seeking to build a website that is more suitable for industry professional. So, this post is more about technology selection and what’s going on with my endeavor now.
“Everyone should have a blog”?
There is a tendency for person who works in tech industry: they love to blog about the technology. I’m not indicating that I’m against this tendency. In fact, I’m super into this idea. That makes programmer life much easier. When we run into technical questions, we can google and usually the solution is presented by some nice guy’s blog post. However, I’m not sure if making blog post is a great way to systematize your knowledge. Let’s take “Minimal Emacs Tutorial” as an example. Let’s imagine how we can translate this article into a blog post. “Learn about Emacs” section can be a post and then I tag it with “emacs-terms”, “emacs-commands”. “HowTos” section is separated into multiple posts because each howto is collected on different dates and as a blogger, I would make a blog post each time I found something new with emacs usage. The tags for “HowTos” section posts may be “emacs topics”. Now, if I want to take a look at what I have learned on Emacs, then I three operations: click on “emacs-terms” to find the posts with this tag, then “emacs-commands”, and finally “emacs topics” to traverse through the all emacs-related posts. As you can see, this is tiresome. Some may argue that this issue can be fixed if we add a theme tag, like “emacs” to every emacs-related post. This can workaround the problem but we need to be very careful about how we choose the tag.
That being said, however, I think making technical blog post’s advantage outweighs its disadvantage. Most important thing about writing blog is that you can keep track of your progress daily. I have been making my personal knowledge base for more than a year. I’m pretty satisfied with what I have accumulated so far. However, there are some caveats. Off top of my head, I need more direct visualization of my progress. I want to see if I can pick up something new daily and that will give me a lot more motivation to push myself to learn more each day. In addition, some page can get enormously long. I have a page called “Collection of algorithms”, which takes like forever to scroll from top to bottom. This page is naturally suitable for blog post by making each algorithm into a post. Lastly, for marketing purpose. Making a technical blog post daily is an enormous effort and it will definitely look good for hiring managers – “Zeyuan is passionate about technology!”. Even though I can showcase my private knowledge base, that is much more inconvenient than a blog post that can be accessed by everyone.
You know you have a wordpress blog, right?
Yeah, I know. WordPress.com is a great place to write blogs. It makes me want to write something each month. However, I want to say writing technical posts on wordpress.com is sort of painful. In general, if you need to insert code, you need to work with “HTML” editor and use
[sourcecode language="csharp"] //your code comes here [/sourcecode]
This format is incompatible with reStructuredText. That means the content written here cannot be rendered using Sphinx-doc engine. That essentially makes the portability of the post to the minimum. In addition, I experience some weird bug when insert the source code. Inside “Sqoop2 7 Minutes Demo with DB2” post, I use lots of SQL statements inside the code block. Everything works fine the first time. However, when I try to update the post, all the quotation marks get translated to the html representation under “Visual” editing tab. I have to manually update all the quotation marks to its symbol form.
What should use?
This is the question that I have been looking into for months. Let me list my expectation first:
- Support reStructuredText
- Static pages should be fine and must feel LIGHTWEIGHT
- Support basic blog functionality – tags, categories, post date
Let’s list out what commonly-seen options are:
Let’s cross Octopress first. I don’t want to touch Ruby ecosystem because the workflow to develop a personal site will completely be different. In addition, there are plugins that let Octopress support reStructuredText but I figure that doesn’t offer full capability like Sphinx-doc does.
Hexo is another beast. It is similar to Octopress in the sense that both of them use Markdown as their major language and it is also rooted in front-end world. I admit Node.js is a pretty cool language and the theme provided by Hexo looks amazng. However, it feels too modern to me and I want to take a little bit more conservative path.
The engine I choose is called Tinkerer. It’s the direct derivative of Sphinx-doc and the workflow doesn’t deviate from the standard Sphinx-doc workflow too much and the setup is quite the same. However, the latest release is back in 2014. That makes me a little worry. But let’s stick with this for now. I can easily switch to Pelican whenever I want to.
What does look like right now?
I’m not going to abandon this wordpress blog. However, I’m going to tweak the direction of the blog posting on this site. From now on, I will keep technical blog post to the Tinkerer-powered site. By technical, I mean that involves code, mathematical expression, and the content that will be part of my knowledge base doc eventually. However, on the other hand, all the life thoughts and any other non-technical posts will still be kept at this site, especially those posts involve lots of non-technical pictures. zhu45.org will still work as the main portal to my personal site until the new Tinkerer-powered site is GAed.