Under Construction (part 2/2)

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

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.

However, on the other hand, wordpress.com blog works best with photos. I really enjoy how wordpress.com manage photos in my “Trip in Nan Jing” and “First Time Ever Hackathon” posts.

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:

  • Octopress
  • hexo
  • Sphinx-doc
  • Pelican

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.

I want to talk about Sphinx-doc and Pelican all together. Sphinx-doc is the foundation to write Python documentation and Pelican is based upon Sphinx-doc and tweak towards blog post. Tweaking Sphinx-doc towards a blog post site requires a fair amount of knowledge of Jinjia2 and some Javascript knowledge. I don’t have enough time for that. So that makes Pelican very tempting. However, I don’t want to use it for now as the workflow and how to control the Pelican behavior is quite different from Sphinx-doc. However, it is definitely worth revisiting in the future just because the size of community and plenty of themes.

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.



Under Construction (part 1/2)

Well, it’s almost the end of November and I haven’t posted anything yet this month. I feel pressured. Lots of things are actually going on this month, which involve my cat, my future career path, and some mentality struggles. I’m not gonna write about them right now because it’s not the right time. Hopefully, I can write about them someday in the future. I cannot promise this.

Today, I can actually write about is my “little” project I just started – building a site. Let me take a break here and give a quick recap. Up till now, building a site or, more specifically, a personal website seems to become my life-long effort.

Everything gotta start from somewhere …

If you are willing to take a quick look, Welcome to Zeyuan Hu’s World! is actually my starting point. I built this site during the summer time of my sophomore year at college. By that time, I was granted a summer research position and my main duty was to help out professor to do computer simulation of some mathematical models. I was just done with my first cs course – CS 302: Introduction to Computer Programming with Java and I heard from my uncle about this Python language. I have no clue among all those programming languages, Python caught my eyes during that time: probably, because of its cool name. So, I decided to give a serious shot at learning Python programming language both for my research job and for my personal interest.

It’s pretty damn hard to pick up a natural language by just skimming the textbook. This also applies for programming language. So, I decide to make notes while I study the Python. Making notes on paper is an option but paper is really hard to carry and easy to lose. When I read about the Python API, I’m pretty impressed by the elegance the Python official website shows and how it can keep everything so well-organized. So, I decide to use Sphinx-doc to make my own site with the main purpose to host my Python study notes. That’s how everything got started.

Making this site allows me to pick up CSS, reStructuredText, Python, and Matplotlib (which I used the library to make the header image of the site). If I evaluate this site under my current level, it’s still a solid website. Even though the aesthetic level may not be high, but the site serves my main purpose well – I got a well-written Python study notes for myself. The downside of this site comes from my personal feeling. I’m definitely not a front-end expert but I can tell this site feels quite HEAVY. There are multiple tabs (i.e., home, projects, cv/resume, and so on) but they are sort of hidden in the way that people have to click through the tab to find the content. This works great if I have accumulated tons of material to demonstrate. However, we both know, this is not the case. Another point is more of a pity. I can no longer maintain this site. My wisc computer lab account id got deleted after I graduated. I still feel grateful that school still hosts my site and that’s very moving policy I have ever encountered.

If you are interested, the source code for this site is hosted on Github. Feel free to check it out and there are some advanced reStructuredText and Sphinx usage in the repo.

Struggles …

My second journey with my site starts shortly after I begin to work at IBM. During the work, I feel the need to build my personal knowledge base. This is mainly  due to the amount of new information you need to keep track of for future use. I feel this is super important for someone who just joined the team and eager to make contribution to the project. At first, I use Sphinx-doc to build up my personal docs like I did previously. This doc or site is not available to public because there is no clear cut between confidential and non-confidential information. For instance, when you try to record the gain from code reading, even though C++ technique is perfectly fine for the public but if we put it under the context of DB2 source code, then the technique combined with DB2 source code is completely confidential. I don’t want to cross the line here. However, every coin has two sides. If some knowledge is completely fine for the public, then I want to share them out. So, building a website once again becomes a task that I need to finish.

I don’t want to get serious engagement with web development (even though I made a try) and on my preference ranking list, easily recording knowledge in a neat way comes first. I don’t want to spend tons of effort working on the web as I feel like understanding database and mastering algorithm sound more fun to me.

Under this criteria, I made some prototypes. The first one is built upon the previous iteration (sphinx-doc web) but incorporates bootstrap framework to make the whole site mobile-friendly and have a modern taste. This one is definitely better than my previous one. I liked it a lot when I first got the prototype out. However, I quickly felt the pain or the pressure of the writing, more precisely. The main purpose is to document my knowledge picked up from the work and it meant to be less reader-friendly. I have to edit some writings in order to make everyone online can make sense out of it. Plus, make distinguish between confidential part and non-confidential part can make this editing thing even worse. More importantly, I still think this site is HEAVY, especially for Chinese because it takes quite a while for everything loads up properly (google-analytics, github servic, and so on). So, I give up. I’m not giving up making my knowledge base but  I give up to make everything public. Meanwhile, I also cleaned up the very first web and adjusted the style a little bit. Unfortunately, this site doesn’t attract me as well.

Before the dawn …

The site I’m currently using is absolutely hideous for my friends (believe me, none of my friends really like it). The main argument they is that this site is just plainly 70s style: it doesn’t even have tabs. That’s true. In fact, that’s kind of the style of I’m seeking: everything is just there. You don’t have to dig the site to find the things you want. Plus, it is super LIGHTWEIGHT. I think this site is perfectly fine for someone who works in the academia: all the publications can be directly seen. In addition, I use a “hybrid architecture” for this site in the sense that I use this site + wordpress blog to host all my writings. By that time, I couldn’t find a proper solution to build a blog post website based on Sphinx-doc and I will talk more about this in my part 2 post.

Putting everything straight out to the reader works well for academia in my perspective. However, it becomes a downside as well: I’m working in the industry. I barely make publications. So, this site becomes really static :(. I hate to actively maintain a site but never update one does no good to me as well. This is actually why I write “This site is permanently under construction.” in my footnote of the page. I know someday I will once again to rebuild this site.


Chronological order of my work on building a homepage