Saturday, January 24, 2015

Moar technical articles!

You need to write more technical articles.

Yes, you.

I could guilt you into doing it. I could tell you that you have benefited from other people's sharing so much that it is time for you to give back.

But instead I will tell you what is in it for you: Job security.

Your real résumé

The classic first step to get a job is to prepare a résumé. It could lead you to an interview if you keyword-stuff it the right way. But nowadays employers are turning to the internet to cross check if you are who you claim. A repertoire of technical articles is a solid way to show that you know your stuff, and more importantly, you can communicate.

But what do I write?

I knew you would say that. While I have no guaranteed formula that works for everyone, I can share how I make writing technical articles a part of my normal workflow.

  1. Experiment on a clean slate
    Whenever I need to incorporate an unfamiliar technology into my work, I do not do it directly in my main project. Instead, I create a brand new project and implement the minimal setup to understand how it works.

  2. Build it up step by step
    Once I get the minimal setup working, I add extra logic to get to what I need. But instead of overwriting the minimal setup, I make a copy so that I can explain the steps later. For example in Android apps I make my MainActivity a list of activities, each corresponding to a step.
  3. Integrate into the main project
    When the sample project has all the functionalities I need, I put it into my main project. It may interact with my existing code in unexpected ways, so I tweak until it works.
  4. Write the article
    After the coding is done I write the article. This is the structure I use:
    1. A back story of what I was trying to do
    2. Outline the steps I took with code snippets and screenshots
    3. Explain the problems I encountered along the way, and how I solved them
    4. Link to source code on github
  5. Push the sample project to github
    I don't publish my source code until the article is written because sometimes I thought of a better way of doing things while explaining my method in writing. Once I am happy with the article, I push my repository to github, publish the article, then add a link from the README of the github repository back to the article.
  6. Share on social network
    After everything is published, I post a link to Twitter and Google+ with a screenshot as the teaser.

End result

Here is a sample article: Partial SlidingPaneLayout

And how I shared it:

Good for you, good for others

I stumbled upon this workflow by accident. I used to stick the new technology straight into my main project, failed to make it work, and unable to pinpoint why. With a brand new project I can focus on the new stuff, work out all the kinks before I introduce the extra complexity of my main project.

Once I figured out how it works, I could have just thrown away the sample project. But what a waste! Instead I push it to github, and suddenly I am an open source contributor. Sweet!

Writing the article is a bit of extra work, but so very worth it. It gives me credibility. It lets people know that I know my tech, and I know how to explain it. Icing on the cake? It helps other people too!

No comments:

Inline coding questions will not be answered. Instead, ask on StackOverflow and put the link in the comment.

Post a Comment