Writing Swift Articles: Tips to become a better writer

Writing Swift articles is a great way to become a better engineer and is often seen as a required skill for Senior developers. By writing down your knowledge or learnings around a topic, you’re creating your knowledge base, which you can revisit whenever you want. At the same time, you’re contributing to the community by sharing your learnings with other developers.

Since May 2018, I’ve been writing a new article every week. Over the years, I’ve learned a lot about writing Swift articles, and I’ve become a better writer through experience. The quality of my first article is not close to the articles I write today, and they took much longer to write on top of that!

Part of becoming a better writer is practicing by doing. The tips I’m going to give you today will provide you with a great head start, but you will still need the courage to keep on writing new articles. Though, I’m sure the tips in this article will make it easier to finish the journey from starting an idea to pressing that publish button.

Why I became a writer

In 2015, I started this blog with the following reasoning:

As iOS developer for my job I found myself experiencing a lot of problems, writing solutions and figuring out what’s the best way to create this UI. Many times these are things to share with others, but until today I didn’t had a place for that.

I was looking for a place to write down my learnings to inspire and help other engineers in the field back in the day. Though, over the years, it became even more apparent why it’s great to have your own written Swift Articles.

Writing down learnings is a great way to remember skills. Whenever I created a cheat sheet at school, I never needed it since I remember writing it down. The same happens with my articles since I’ve become a better engineer due to writing them.

Another benefit is being able to revisit your articles. I often find myself revisiting my article Swift Package Manager framework creation in Xcode when I’m starting a new package since I know the article describes how I want to create new packages.

Writing Swift articles also allowed me to grow in the Swift community. I gained many new Twitter followers, making it easier for me to join podcasts and speak at conferences since organizers know who you are. A personal blog is like a bag of knowledge that can convince others about your skills. I’m pretty sure you’re making a good impression at a tech interview if you’re able to show a personal blog full of knowledge around Swift development.

Now that you’ve got reasons enough to start writing, it’s time to define your audience and writing environment.

Defining your writing environment

Your writing environment sets a direction to use when determining new writing topics. To me, it’s not only about creating a writing audience but more about creating a writing environment. Questions I’ve often asked myself:

  • Who am I writing for?
  • Why am I writing Swift articles?
  • What do I want my audience to learn?

These questions helped me define the environment I’m writing in every week. Try to answer these questions for every article you write to create boundaries that will help you publish faster. It’s OK to answer the questions with the same answers since you’re likely writing for the same reasons and audience.

I’ll share my answers to give you an idea of how this helps me write Swift articles.

Who am I writing for?

Even though I’m writing articles to help the Swift community, I often state that I’m writing articles for myself. I want to revisit my articles and gain knowledge when working on a specific topic. Thinking this way allows me to publish the writing whenever I want. In the end, “I’m writing for myself,” so if I’m happy, I can publish.

Why am I writing Swift Articles?

As a Swift engineer, I need to stay on top of new technologies and learn along the way. I do not forget about the wisdom I gained by writing down my learnings. I’m also creating reasons to dive into new topics by writing frequently. In other words, I’m writing Swift articles to stay up to date as a Swift engineer.

What do I want my audience to learn?

The topic I’m writing about should be clearly described, almost in a way that my mom would understand. Taking this into account requires me to explain issues clearly and to the point, resulting in short and focused articles.

What do these answers have in common?

For me, all those answers come down to the fact that I’m writing for myself. “Writing for myself” sounds quite arrogant, but it’s just a mindset that helps me deliver articles frequently and help you progress with my learnings.

The answers to the above questions should help you set a direction allowing you to write Swift articles more easily. Say you’re an experienced Swift engineer, and you’ve defined your audience to be of the same level; you don’t have to worry about explaining how to create a new project in Xcode for your articles. By knowing what you want your audience to learn, you’ve set a finish line which you’ll reach with your article after providing the learnings.

Finding a topic to write about

A question I often get asked is on how I find a topic for my Swift articles. I would not be surprised if finding a case is the biggest reason for many engineers not writing anything. I especially think so since the question is often followed up by:

“Somebody already wrote about this topic”

Which, in my opinion, is not a reason not to write about a topic again. I wrote many different Swift articles covering a lot of ground regarding Swift techniques, but I still find myself visiting other blogs to gain extra insights. Even though I wrote a pretty advanced article on Property Wrappers, it still does not cover property wrappers for local variables. Other articles in the community fill that gap while writing about the same topic.

Your writing and your vision on a topic are different from others. There’s always a place to share your learnings and insights. There’s also always someone that will love your way of describing a solution. Don’t stop yourself from writing just because another blog already covered a topic.

So, how do I find a topic?

Right, I was losing my point a bit in the previous paragraphs, ha! Yes, finding topics. When I’m picking a topic to write about, it either starts from learning I gained or from an interest in a specific subject.

Writing about a learning you gained

In my day-to-day job at WeTransfer, I’m learning a lot of new insights, which I often write about later. A few weeks back, I wrote about Reflection in Swift: How Mirror works, containing a copy of an implementation I wrote for the WeTransfer app. Writing about such a topic makes it easier to write Swift articles since you’re writing down the learnings you’ve already gained.

It’s not always possible to directly write an article about such learning, which is why I’m keeping track of these topics inside a Trello board. Whenever I cannot develop a topic to write about, I revisit this list and pick a case for that week.

Writing about a topic you’re interested in

A second approach I often take is picking a topic I want to learn. Last year, async/await was introduced and quickly became a category on its own at SwiftLee. Since I want to stay up to date as an engineer, I decided to learn about the different concurrency APIs and write down my learnings along the way.

This approach works great for unfamiliar topics. You often need to learn these topics either way, so why not write down an article simultaneously?

Another perspective

My approach is not like others, so I decided to ask Vincent Pradeilles for his perspective. Vincent publishes Swift content on his YouTube channel, covering many different topics.

”My number one source of inspiration to come up with new tips is new language features. Whenever new features get added to Swift, there’s a very good chance that it will open up the way for some cool creative use cases. So I would recommend paying attention to the WWDC sessions “What’s new in Swift”, the release notes of each new version of Swift and even the Swift Evolution Proposals.”

Vincent Pradeilles

Structuring your articles

Once you’ve got a topic to write about, it’s time to create a structure for your articles. Structuring your articles is essential to make sure it reads nicely and answer all topics you want to cover.

Whenever I start writing a Swift article, I write down the questions I want to answer. For this article, I asked Twitter, which resulted in quite a nice list of questions. The next step is to create section headers for each part of your article. For this article, it resulted in the following structure:

Writing Swift Articles start with creating a structure that answers the questions you've had in mind.
Writing Swift Articles start with creating a structure that answers the questions you’ve had in mind.

As you can see, it roughly contains all the headers you find in this article. By starting with a structure, you’re allowing yourself to overview the structure before writing any details. This technique works great for me since it results in a logical structure which makes the article easier to read.

Creating such a structure also results in focused paragraphs answering specific questions. Covering too many parts in one enormous section is much harder to digest for your readers than a short and to-the-point paragraph answering just a single question.

To give you another perspective on structuring articles, I asked John Sundell for his view. John has a lot of experience in structuring articles since he recently published his 500th (!!) article on his blog Swift by Sundell. Here’s the tip from John:

“I think the most important thing when it comes to article structure is to try to divide each article into separate segments that each focus on one specific subtopic. For example, if you’re writing about arrays, you could have one section about how to create and append elements to an array, one section about iterations, and then perhaps one section about APIs like forEach and map. That way, you’re not presenting the reader with too much information at once, and you’re sort of turning up the complexity as the article progresses.”

John Sundell from Swift by Sundell

I like the idea of building up the complexity as the article progresses. John takes into account some of his readers might be new to the topic for which it helps to expose more complex details slowly. At the same time, it allows readers that are more familiar with a case to skip to the more advanced sections.

Creating a writing habit

Now that you know how to create a structure and find a topic for your Swift articles, it becomes a challenge to create a writing habit. Writing frequently allows you to learn and contribute to the community continuously. Consistency will also improve your writing, making it easier to write new articles.

My writing habit started in May 2018 when I wrote a new article every week. The insights I gained from my visitor statistics motivated me to keep writing. By creating consistency, you’ll let your readers know there’s a reason to come back next week to find a new article to read. Developers will start to follow your work, and you’ll gain more and more visibility. My daily visitors’ count went from 24 in 2018 to 3000 in 2021. You can imagine the latter is much more motivating than knowing you’re writing for only 24 readers.

Creating a writing habit comes down to creating a motivation to write. A part of it is the mindset of:

As an engineer, I need to stay up to date on new topics either way. So why not write about it?

This mindset will help you start writing more frequently until your stats grow. Eventually, you’ll gain more visibility with your articles, which is a great feeling. You begin to realize you’re helping other engineers in the community to progress. Gaining visibility takes time, but there are a few tips I want to give that will help you grow:

  • Create consistency and with that reason for your visitors to actively follow you
  • Share your articles on sites like Twitter and Reddit
  • Add your RSS feed to iOS Dev Directory. Many newsletters, including SwiftLee Weekly and iOS Dev Weekly are using this list as a source of articles to cover in their issues.
  • Re-share your articles! I’ve got examples of tweets covering an old article that gained 300 likes for the past 2 years. Your article might be old to one engineer, but new for many others.

Motivation and consistency will hopefully get you closer to a writing habit. The tips from this article will help you write easier, making it more fun to write new Swift articles. My first article took me longer to write and was much shorter than the articles I write today. Give yourself the time to grow as a writer!

I asked Paul Hudson to share his tip on creating a writing habit for this section. Paul has been writing articles for a long time on his blog called Hacking with Swift and has published several books over the years. He created that writing habit for himself, which he proved by the fact that I asked for a single paragraph, which resulted in “One paragraph didn’t happen; here are four paragraphs 😛”:

Do what works for you

It can feel fantastic to be able to write down your knowledge and share it with the world, but don’t be discouraged if you’re struggling to find an approach that works for you. Some people write an article once a week and swear by that approach; others write a little each day and bring it together only when they feel they’ve said what they wanted; and still others have a big long list of ideas they just work through steadily.

My approach is none of those: I write only when inspiration strikes me. Sometimes that means I do nothing for a week or two, but other times I’m wrapping up a big project and thinking of 10 or 20 things I can pull out from there that make interesting examples I want to share.

If there’s one tip I do live by, it’s from the author Roald Dahl. His advice was always to stop writing in the middle of an exciting part of the story – rather than end the day by finishing a chapter in one of his stories, he would instead finish just in the middle of something exciting happening because it made it much easier to pick up the next day. This is doubly important for me because I try to avoid working whenever my kids are at home, so I stop and start work quite a lot in order to spend time with them instead.

So, if you find writing on a schedule works for you, that’s great! If you prefer to write only when you’re inspired, that’s great too. The main thing is that you do what works for you, at a time that works for you, and you enjoy the ride.”

Paul Hudson from Hacking with Swift

Paul shares some great thoughts, for which he made me realize that the definition of a writing habit is different for everyone. I’ve been suggesting writing consistently, which could mean writing every week if you look at me. Though, like Paul says, finding the schedule that allows you to “enjoy the ride” is the main thing that counts.

Creating the confidence to publish

The last section I want to cover is creating the confidence to publish. I often get asked how I manage to publish my articles frequently since many start a piece but do not finish it. What works for me is to start writing an article and pressing the publish button right after. I’m never finishing an article the day after since, for me, it often results in rewriting the article instead of finishing it.

In a way, it’s not only about confidence to press that publish button, but it’s also about getting to the point of being fulfilled enough with what you wrote down. The idea of “I’m writing for myself” works excellent to publish whenever I want. I don’t have external expectations that make me scared to post, and I’m not afraid of the feedback I’ll get. If I get feedback that I wrote something wrong, I’ll receive it gratefully as it allows me to improve my learnings and article.

Nothing should stop you from sharing your article. There will always be readers that dislike your writing for several reasons, but why not think about all those readers that do enjoy what you’ve written down?

Think about the tip from Roald Dahl that Paul just shared in case you’re struggling with finishing up an article in one go. It might be better to pause writing halfway when it’s still exciting since it makes it easier to pick up writing the next day.

Conclusion

Frequently writing Swift Articles might be challenging. The tips from this article will hopefully help you enjoy writing articles more often and become a better writer. Give yourself the time to progress as a writer since it’s a skill you can train. I can’t wait to see more engineers publishing articles in the community, so make sure to share your RSS feed with iOS Dev Directory so other newsletter creators and I can find your articles.

If you like to prepare and optimize, even more, check out the optimization category page. Feel free to contact me or tweet me on Twitter if you have any additional tips or feedback.

Thanks!