Become a Better Engineer Through Writing

For developers, it is often much easier just to write code, rather than explain and defend your implementation to others. However, in team development, it is not only necessary but also crucial to be able to communicate your technical ideas clearly. What is the best way of refining your thought process? Writing! Using various forms of writing, you can learn several approaches that will help you become a more thoughtful engineer. In this AltConf talk, Kristina Thai discusses how to use writing as a form of technical expression. She hopes to inspire you to take charge of your career by proactively working on your technical communication skills in a medium that many engineers tend to shy away from. On a personal note, Kristina shares her journey of how technical writing helped turn her from a nobody with barely any iOS development experience, into an internationally invited technical speaker in just 1 year.

---

Introduction (00:00)

I am super excited to talk to you about how to become a better engineer through writing (a subject that is near and dear to my heart). Over this past year and a half, my life changed: I will walk you through my story, and about writing in general.

My name is Kristina Thai. I am an iOS engineer at Intuit, specifically QuickBooks Self-Employed applications; if you would like a better way of looking at deducting some of your taxes, this might be an app you want to check out. My main passion has been Apple Watch development: I spend a lot of time writing Apple Watch tutorials for my blog, and that has been my main gateway to iOS development in general.

I know that many people probably saw my topic and when they saw the word writing… they probably ran in the other direction. But, many of you probably wanted to figure out, how do we become better engineers? Let’s take a step back: what exactly makes us a good engineer?

What Makes A Good Engineer? (01:21)

I have come up with a Engineer Checklist:

• Technical skills. We want strong coders to be engineers. Many times some of the best engineers are also domain experts - you can rely on them to be an expert in any type of information that they advertise to be, as well as problem solvers. You are determined to work through any type of problem that you come across.
• “Soft” skills. Even though many of us emphasize the technical skills of being an engineer, some of the best engineers have strong soft skills, and this makes them shine even greater. We all want to work with people that can communicate, and have a great passion for learning. All of us should be striving every day to learn something brand new. We love to learn from our mistakes and make sure that we do not repeat these in the future. Also, and this may be optional, some of the best engineers are great teachers and mentors. Not only do they help other peers, but they also help the younger generation get better at their own engineering skills, and be able to pass on all of that information for later.

What Does This Have To Do With Writing? (04:03)

When we think of engineering, we do not think about writing. Would not it be great if we could write code like this - we think about what we want, and then it magically appears on the screen? The Ph.D. comics (see slide 6) is about writing essays and dissertations. Many times, engineers and writers go through very similar processes. Here’s a quote from Shubhro Saha:

“Code and essays have a lot in common. The product is a sequence of logical statements bundled into modular units, whether it be functions or paragraphs. Like good prose, good code is concise. Bad code wastes CPU cycles, and likewise, bad essays waste brain cycles.” Hence while code and essays produce relatively different things, in the end, the process of writing essays and writing code is very similar. You are taking all of these jumbled thoughts in your head, trying to lay them out in a logical order.

There are four different writing channels (more fun than writing essays) that can benefit engineers: personal journals, Q&A forums, blogging, and technical tutorials.

01. Personal Journals (06:42)

Personal journals are a private place to record your technical challenges. It is a great way to reflect on a particularly difficult bug that you have worked on today, or at a more high-level you can look back at how you architected your code for an app, and ways that you could have made it better. There is a saying that goes, “if you are happy with your code that you wrote a year ago, then you probably have not learned enough in the past year”. Being able to look back at a personal journal is a great keepsake to see how much you have grown as an engineer.

There are many benefits to keeping a personal journal. It is for your eyes only; if there is something that might be embarrassing and you might not want to admit to a coworker, or post it publicly, it is a great place for you to write out those silly questions and thoughts in your head without any negative repercussions. It is also very easy to get started. You could break out a laptop, and start writing a personal journal on your computer in the next minute.

In terms of challenges, they are primarily motivation-based. If you are not very motivated on your own, keeping a personal journal might be hard to keep up, primarily because you will not have many external people pushing you to write. That is where many people can fall off the writing train. It also does not benefit other people. While it definitely does benefit you and it is a great reflection on all of your history, you cannot teach others and have them learn from your mistakes (and potentially keep themselves from committing them in the first place). In the rare case that you might be wrong, there is no one to correct you.

If you think back to that engineering checklist, personal journal covers a decent amount of it: it covers all of your technical skills and adds in a couple of soft skills that you can also learn from personal journaling.

02. Developer Q&A forums (09:25)

Developer Q&A forums are places to get help with your technical problems. In this area, knowledgeable experts, or people that think they are experts, will answer your questions.

Stack Overflow is probably one of my best friends that helps developers day and day again. It is generally best for fairly objective answers. For example, this question, “How do I concatenate or merge arrays in Swift?” has a straightforward answer. There are a couple of different variations on how you can do it, but there has been a general best practice of how you can concatenate or raise. You can see that many answers on Stack Overflow push for having one or two great direct answers.

An alternative site is Quora. You may not think about Quora as a good place for development questions, but you would be surprised. Quora differs from Stack Overflow: it is better for open-ended answers, where multiple things can be right. If you look at this example, this person is asking, “What are some well-built open-source iOS applications that can be studied for best practices?”. Everyone would probably have a different answer, and they would all be correct.

We also have many benefits in developer Q&A forums. Especially if you are a beginner, it is great to learn what other people are struggling with. Many times, we might have silly questions in our head, and we are too afraid to ask them because we do not know if other people are going to laugh at us while we are learning. But, when you get to see all the questions that other people are asking (e.g. that first one for the Swift array concatenation - a simple syntax issue), many people may have had that question themselves. You never have to feel silly for thinking you do not know something that is as simple as a syntax issue.

In opposition to personal journaling, with developer Q&A forums, any time you see a question that you can answer, you can answer it right away, without having to set aside that extra time. Additionally, it builds reputation. Since these answers are tied directly to your username or actual name, you can start showing that you are an expert in certain areas.

In terms of challenges for developer Q&A forums, you may or may not come across some negative comments. Unfortunately, some of these communities can be unforgiving if you are ignorant of the rules. Again, Stack Overflow is great for direct objective answers, but if you try to start a discussion or add comments that do not help the community, you might get downvoted or even get negative comments. As a woman too, in particular, I remember coming across an instance on Stack Overflow where a woman had posted an answer that was not entirely correct, and she received a few upvotes for it because other people did think she was correct. But there was a comment directly underneath that from a guy that said, “The only reason you got many upvotes is because you have a pretty profile picture.” You can see where some of the hostility can come out, even though people generally tend to be well-meaning.

03. Blogging (14:52)

Blogging, which is probably the most popular form of technical writing, is generally a public place to report all of your technical challenges. That is very similar to personal journaling, except it probably needs more polish since this is going out on the internet, and we will want to have some solution at the end. In your personal journals, you may have open-ended questions, and that is okay because that is for your use only; regarding blogs, many people want to know what solution you came up with and where you ended up going at the end.

I have some great examples of blogs here:

• Ayaka writes an amazing blog on different Swift concepts. What creates a great blog is that these blogs tend to have very similar themes, and attract a specific audience. If you want to be able to keep a specific audience in mind, then you will want to focus your blog on a very specific topic. One of the challenges with blogs, though, is that it may be hard to keep up your content and keep it fresh because you might not have time to write as many blog posts.
• Another example of blogging is a community blog. NSHipster is one of the greatest examples of this: a team of collaborators weekly go through overlooked bits in Objective-C, Swift, and Cocoa. Another form of community blog is a corporate blog. If you are interested in contributing one or two times to a blog post, and not necessarily starting up a community altogether on your own, check if your own company has a corporate blog themselves. It allows you to have name recognition off the bat, and you can use your corporate brand to promote your posts without having to go through that trouble yourself of marketing everything.

Blogging has public exposure and builds your reputation. It has the added benefit of reflection time for you to look back at all of your online posts. In terms of challenges, blogs require a lot of time and commitment. It can also be hard to keep your blog fresh and unique (especially if there is no brand news, or you have not worked on anything that is newsworthy). Blogging covers every single item on my engineering checklist - even though it takes up more time, it benefits you the most.

04. Technical Tutorials (18:26)

Technical tutorials are step-by-step walkthroughs of specific projects, and they generally have a working demo project at the end. Natasha has one of the best tutorial sites. That is where I learned all of my watchOS development before I started in it (I am in debt to Natasha for learning how to do Watch development). If you are worried about keeping things fresh, you may consider joining a community or forming a community site. Ray Wenderlich has an army of people writing tutorials for him every day, including video tutorials!

Technical tutorials are the very best to build reputation. You can say all you want about something, but if you are not putting your words into action, it is not as great. It is also the best way to reinforce your own learning. If you can teach others how to do it and explain it in layman’s terms, then you have this topic down; and one of the best parts about doing this is that you get to build out full projects too. Many times, people might be worried if they are taking the time to do writing (it is taking away from their coding time), but luckily this lets you have the best of both worlds.

However, this takes even more and more time and commitment than even blogging does, because you are essentially doing the work twice. First, you write the working project, taking that and translating it into your tutorials themselves. It is difficult to find unique and undiscovered solutions. There are a bazillion UITableView tutorials out there - that is an example of something that is been pretty much “over-tutorialized”, and it can be difficult to find some unique stuff if you have not had a chance to explore any other areas of iOS development. Our checklist has grown fully here too - we have pretty much marked off every single item again.

My Journey (22:03)

This may seem like too much information. Is it worth the time and effort? I personally cannot make that decision for you, but I can tell you about my journey over this past year and a half, and let you decide from there.

I started out writing answers on Quora, and posting random stuff about iOS development that I thought was right, and it ended up not being right in some respects. But people were nice enough to correct me and teach me how to get better. After that, I branched out into writing tutorials. I started playing with the first beta for WatchKit, and it was great. It was completely uncharted territory that nobody else had had a chance to explore, and I started messing around with the betas, Googling for answers. The unfortunate part about playing with brand new betas is that no one else has had a chance to do this, my Google results only came to the Apple developer documentation, and nothing else. I ended up playing around with it myself, and I eventually figured it out. In this particular beta, it was the very first time that you could send data from the watch over to the phone, and it was a huge deal. There had been no way to do this before. When I figured it out, I was excited, because I was probably one of the first people to get it to work. I decided to write a quick tutorial in December of 2014 and, eventually, it was noticed. It was the first thing out there that even explained how to send data from your watch to your parent iOS app. I became addicted: I started writing more and more tutorials for Watch, and they eventually were noticed.

My blog posts started appearing in newsletters. After that, it spiraled out of control. I was very lucky to get one/two hits on my website a day, and then it rose the more tutorials that I wrote. One thing to note, if you take a look at the very end (see slide 29), you can see that dip in my hits. That shows you how much time and effort it does take to keep up something like this. I went on a month-long vacation around that point, and all of my website stats started to drop because I had not been posting. But when I came back, you can see it picked up again. Nowadays I average about 300 views a day, and up to 500 if I have written a new blog post for that particular day.

I started getting asked to contribute to other blogs: e.g. a Realm blog contribution, which was one of the very first ones that were written about Watch, and it was even featured on Daring Fireball. Six months after I wrote my very first blog post, I was invited to speak at my first conference, Swift Summit. From there, it has been insane. After a year and a half of writing, I have gone from a nobody to an internationally invited technical speaker in that short of time.

If this sounds like something that might be interesting to you, I highly suggest that you get started writing yourself. I know not everyone goes through that same journey, but you never know what opportunities lie ahead, and this might be the change you need to dramatically turn your career into a different direction.

Getting Started (27:16)

All of these writing channels cover technical skills - you may also want to focus on the soft skills that you want to learn. Depending on what soft skills you want to improve, that is where you are going to pick your different types of writing channels. If you go back through the slides, you will be able to see those engineering checklist stickies, and decide which ones you want to use from there. But, if you have already figured it out, I am going to go through all of the different ways that you can get started with this.

01. Personal Journals (28:13)

With personal journals, the easiest way to get started is to create a private online one. It will set up all of that content for you, and you can focus on the things that you want to write. I have some links to create a private Tumblr, and to adjust privacy settings on a WordPress.com blog.

Alternatively, if you do not want to post anything online, you can also post on offline journals, or in other writing platforms. I highly recommend the Day One app as a journaling tool. Unfortunately, it does not give you ways to write code in it or to have syntax highlighting, but it is a great journaling app in general. You can always pick up your favorite text editor or Evernote, for example.

02. Developer Q&A Forums (29:17)

In terms of developer Q&A forums, make sure that you follow community rules and communication styles. As a tip, you can choose a non-technical question to answer first, if you are more comfortable doing that; and eventually posting technical topics.

03. Blogging (30:15)

Choose the blogging platform that you want to write on: depending on if you want it to be hosted or self-hosted, this will be where you make the differentiation. Medium is one of those places that is easy to get started, but it also offers the challenge where you do not have many personal branding with that. It is mostly more of a community site. WordPress, on the other hand, is a very robust and complex platform tool, but it can be very powerful if you know how to manage it. I personally use WordPress to blog all of my posts, and I have highlighted two different plugins that are useful if you are thinking about using a WordPress blog. In particular, we have the syntax highlighter plugin, which allows you to customize your blog to enable you to write code in it, as well as the WordPress security plugin. WordPress is so popular that you get many people trying to hack into your blog, and having a security plugin is a great way of preventing those hackers from coming in.

In terms of the blogging process, these are general steps to start writing blogs:

• Decide on a topic. When writing the post itself, you will want to lay the foundation, or describe the context. In this case, what exactly makes this particular topic unique from other situations? For example, if you are writing about UITableViews, there are many blog posts on UITableViews - what are you doing differently than other people that makes your post unique?
• Highlight various approaches that you have been through within your technical exploration, and walk through your process, or any options that other users can come across.
• End with the most optimal solution that you have had or that you have figured out, or even with a question if you have figured out a bunch of different ways of doing it and you cannot decide for yourself.

What is great about blogging is that you will get many comments on your blog: people telling you exactly how you should be thinking, or making you consider other options. It is a great way not only for you to get your own story out there, but then learn from other people who might have had more experience than you.

In terms of motivation, I know blogging can be very difficult to keep up. Here is a story about a woman who had a travel blog: she wrote consistently every day for two years and never broke over 100 visits a day. She had a couple of bumps there in traffic (see slide 44) but, in the end, she ended up coming back down to her initial visits per day. It is around this time that most people tend to give up… and they give up too early. Nowadays, she gets over 100,000 visits per month, and her hard work grew exponentially. I linked this great blog post on the insanely slow road of building a blog.

Even though it might seem hard and it might seem frustrating at times, eventually it will pay off. In particular, iOS is fairly different than other blog spaces, because one newsletter or one Tweet might make all of the difference - that is what happened to me. When I first started posting about my Watch staff, Natasha the Robot picked up on it, and that is where all of my popularity came from. Besides that, I recommend these other links for motivation:

• How do I keep up with it all: blogging, online life & more
• 5 ways to keep your blog content fresh
• How do I start a blog and keep it up? - Quora
• You should write blogs
• Software engineers should write

04. Technical Tutorials (35:30)

Technical tutorials follows very similar steps to blogging:

1. Decide on a topic. Remember that this topic does not have to be all-encompassing; depending on your audience, you may or may not decide whether or not you want to start from the very beginning, or skip ahead to the more meaty part of the tutorial. When I first started posting about Watch development, for example, I started from the very beginning: from creating a Watch project, to driving in an interface controller, to running the Watch app on your simulator. That is because no one else knew how to do it, and I knew that my audience probably had no experience with Watch development. Later on, my tutorials skip past that part and focus on the content at hand in my actual Watch code. You can see that the transition from one end of the spectrum to the other because I now assumed that my audience has changed, and they have more experience. Another way that will help you decide on a topic is to check out the latest questions on Stack Overflow. Many times when people do not have any idea how to do something, you can pull a great topic out of these latest questions and build it yourself, and post it as an answer.
2. Create a working project or working code samples. Many people want to see a working project in the end - here is where you get a chance to build that full project yourself.
3. Create a step-by-step tutorial based on your project and code samples (see this tutorial and my first one). Screenshots and copy-and-paste snippets are very helpful because many people, when they are going through your tutorial, want to be able to see exactly how to do something, even though it might seem a little obvious. It is better to overexplain and overcommunicate than to underexplain. If people are going through your tutorial and they get frustrated, they will probably close the browser window and never come back. Making sure you overexplain will let people finish your tutorial from end to end. You can also include a starter code project. That will allow you to skip past some of the bits that they have already learned, or any of the boilerplate code that you need to set up, and focus on the main content that you want to teach.
4. Upload your project to GitHub.
5. Upload your project to your website.
6. Advertise your blog posts and tutorials on Twitter or social media. You can use hashtags to let other developers know this is out there. #iOSdev, #swiftlang, and #watchOS are very popular hashtags. You can also tweet at newsletter accounts and influential people to make sure that your tutorial is heard. If you ended up writing this as an answer to a Stack Overflow question, make sure you post your tutorial to the answer to that particular question.

Tips for getting started (39:11)

You do not have to be the expert. You can start by writing a narrow post and expand out, or do a very high-level one and then go into more detail.

Another way that you can find good topics are to check out your side-projects, as an example for a tutorial or a blog post.

Last but certainly not least, find a blogging buddy. This is probably my number one recommendation as a writer. Not only is it great for keeping both yourself and other person motivated, but you can use them as a guinea pig and let them walk through all of your tutorials and your blog posts first, before the rest of the world sees it, in case there might be something wrong. If you get started writing blog posts or tutorials, I am more than happy to read your post for you too.

Q & A (40:41)

Q: What are some things that keep you motivated personally in creating tutorials and putting it out there, and not being self-conscious of what people might think? Kristina: I get that question a lot. In terms of motivation, I honestly find that any new content out there motivates me to learn more about it and write about it. Of course, this week especially, it is iOS Christmas. We have all the presents that we want during this time of year, and I take time afterward to spend watching all of the different sessions, and then writing blog posts about that because I am really excited about everything that comes up. On that note, watchOS 3, super awesome. I was bouncing off the walls when they were doing it. That is one of the ways that I keep motivated, not only seeing what Apple presents, but what other people end up finding out from it. Taking the time to read other people’s blog posts and other people’s tutorials motivates me too, because I get to see what cool stuff they have done, and then see if I can explore that path some more. In terms of not being self-conscious, I am totally with you. I definitely have impostor syndrome sometimes. I even had it coming into this conference, because I did not submit for the call for proposals, because I did not think anyone would be interested in anything I had to say. But luckily, the people invited me and, because all of you are here today, it makes me feel great that you are actually interested in writing. I am super excited about that. In terms of being self-conscious, it is something that I feel I had to get over; once I published that very first blog post, I agonized over it for probably two or three days before I posted it, two or three days after it was completely done and finished. I had a bunch of comments of people that were positive, and some comments that were not positive, but I ended up taking those comments and learning from them, and applying it to my next two tutorials. I take a look at any negative feedback as a learning opportunity towards the future.

Q: You talked a lot about communicating between developer to developer. Do you have any direct feedback to designers or the design community on how they could better communicate to you, to bridge that gap? Kristina: That is a great question. It is funny; I used to be an interaction designer. I did that for about six months before I decided I was terrible at it. It comes back to the tutorials. Being able to overly explain and overly exaggerate what your intentions are between designers and developers makes a difference. Many times we make assumptions as developers and assume that designers know about something. Or even the opposite way around - designers may make assumptions about how developers think and react too. Overcommunication helps. On a different note, I would say making sure that you are both on the same page in terms of the terminology that you are using can make a difference there too. I know that not many designers have that technical know-how; but, if they can agree on what certain things mean to each other, being able to explain things to each other makes it easier when you are using the same terminology.

Resources

• kristina.io
• My Biggest WatchKit Mistake - Realm
• Make a private Tumblr blog - HowToGeek
• Privacy Settings - Wordpress
• Day One app
• Evernote
• Community rules - Stack Overflow
• Communication styles - Quora
• Medium
• WordPress
• Syntax highlighter plugin for Wordpress
• Security plugin for Wordpress
• The insanely slow road to building a blog (and why most people give up)