Blogging: Writing

On 28th March 2011 I published the first ever blog post to Styling Android. Almost 9 years later there are now, as this is published, some 459 published articles. When I first started out, I did not have a clue what I was doing, and some might say I still don’t! After writing so many posts I have found a process and rhythm for writing blog posts which seems to work for me, and it occurred to me that it might help others to find their own blogging voice to share how I go about it.

In the previous article we discussed how I personally generate ideas for possible blog posts. The good initial idea is key. That may sound like stating the obvious, but over the years that I have come to know quite early on if an idea is likely to play out – mainly because of what was discussed before about getting a feel for whether I feel I can bring a new perspective or insight to a subject compared to what material is already out there.That said, a good idea is only a starting point and there is still a couple more stages to go through before I have a completed blog post.

The next stage for me is to write the supporting code for the article. Regular readers of Styling Android will know that I like to include a link to the supporting Github repo at the end of each post. Occasionally I am unable to, but I feel it important to provide working code for each article.

The reason I try and write the code first is that the process of actually getting the supporting code working helps me to gain a much deeper understanding of the subject at hand. In many cases I find edge-cases and gotchas that would not have surfaced if I just tried to write the article text first. When I was first starting out I tried writing the article text first, then the supporting code, but I often found that I would have to re-write the article text once I got the supporting code working, so I quickly switched these two stages around.

This is another part of the funnel that I mentioned in the previous article: Sometimes ideas fail at the support code writing phase because I am unable to get something working. Thankfully these tend to be quite few and far between, but when they do happen they consume a lot of time because I invest quite a bit of time in trying to get them to work. As I’m writing this article I have one that I’m struggling with a little. Hopefully I’ll get that sorted and you’ll get to see it soon!

Another thing worth mentioning about my code writing stage is how I use Github. I actually create two Github repos for the supporting code for each article or series: A private and public one. For the AnimatedIcons series there is a public repo named AnimatedIcons (surprisingly!), but also a private one named AnimatedIconsPrivate (which you won’t be able to see). Initially both repos are created as private ones, and when the blog post (or the first article in a series) is published I make the public repo available publicly.

I create scratch branches in the private repo, and make multiple commits until I have working code. I also have my own Jenkins CI which performs static analysis on the private repo so I have some basic code quality checking in place, and these frequent commits trigger CI builds. They also enable me to switch development between laptop and desktop machines quite easily.

For a standalone article I use the main branch, but for a series, I create a separate branch for each article in the series, which allows me to include links for the separate branches in the written articles. When the code in my scratch branch is ready, I make a PR to either master or the article branch. This is not for code review, but simply because I can squash the commits. I do this for a couple of reasons. Firstly it allows me to commit horrendous stuff safe in the knowledge that people won’t see it in the commit history, but also because I can also be safe in putting possibly sensitive stuff in my commit history, which can be removed further down the line – before it goes public.

As an example of this, the work-in-progress that I’m struggling with a little uses a third-party API key which I initially hard-coded and committed to the scratch branch. I have since moved it out of the repo so that I can publish the code without exposing my personal API key. If the full commit history were made available in the public repo then that API key could be seen by going back through the commits. The squash merge compresses the individual commits, so I have complete confidence that nobody will be able to extract my personal API key from what actually gets pushed to the public repo (even though it’s still there in my private repo).

The final stage of the process is writing the article itself. As odd as this might sound, I find this pretty easy but that’s because much of the hard work has been done once I get to this stage.

I try and structure my posts in a clear narrative – any form of writing is a form of storytelling, even technical blog posts, so I think it is important to have a clear beginning, middle, and end to the narrative.

I try and achieve this by starting with stating the problem we’re looking to solve. I think this is important because it enables the reader to make a conscious decision if this is actually relevant to them. There’s no point in trying to mislead people, imo.

The majority of the article is the process of solving that problem. This is documenting the important bits of the supporting code – I long since stopped explaining every single line of code. The important bits are usually pretty obvious to me having gone through the process of writing the support code. This is also where I tend to cover any gotchas or tricks that I encountered while creating the support code.

The closing is summarising how we got from the starting problem to the finished result. If this is a part of a series and there are further posts to come, then I’ll usually give a small clue as to what’s coming next.

The only thing left is to actually publish. I don’t publish as soon as I have a post completed because I set my self a (stupidly!) aggressive posting schedule of once a week. I am usually working in my day job at 10am on a Friday (UK time) when my weekly post is published, so I have largely an automated publication. The actual publication, and social media messages are lined up and handled by WordPress (the blogging platform that I use). All I need to do manually is to make a Github repo public, or push a branch to the public repo which takes a matter of seconds.

That’s how I go about blogging. It’s a process that has evolved over the years, but is how I currently go about it. It will not work for everyone, or perhaps not many people at all, but hopefully folks may be able to take pats of my process and adapt them in to techniques which work for them.

Happy blogging!

Many thanks to both Claudia Luque Fernandez and Filipe Mendes for proof-reading this article and providing some valuable feedback which helped to improve it.

© 2020 – 2021, Mark Allison. All rights reserved.

Copyright © 2020 Styling Android. All Rights Reserved.
Information about how to reuse or republish this work may be available at http://blog.stylingandroid.com/license-information.