Rambling Reflections • Twelve Months of The Python Coding Stack

When I started The Python Coding Stack one year ago, I had one rule: Ignore all other rules. This is a personal essay to mark this arbitrary milestone.

I don't like breaking rules. Or so I used to think. But as I grow older, I've learnt to be more selective on what rules to follow. Some rules are just dumb. They're the ones that should be broken. Others are just not for me.

When it comes to technical writing, I've been on a journey throughout my technical writing career. I'll tell you about this journey, but let me start exactly twelve months ago.

A series of fortunate events led me to start a new substack–this substack. I had written about Python before and had started exploring new avenues for my writing style. But with this publication, I set out with a mission. I didn't want to write boring articles. "Technical articles are meant to be informative and educational, not entertaining", I hear some say. They're wrong. Technical articles are more effective when they engage the reader and provide the best way to explain a topic to ensure the reader understands and recalls the concepts. I didn't want to follow a strict template that all classic tutorials follow. I didn't want to follow silly rules. In fact, I didn't want to follow any rules at all.

So I took all the writing practices I learnt in my academic scientist days and all the rules that make a "good" tutorial, I bunched them all up in the garden and set them ablaze in a bonfire of rules.

I decided I'd write the articles I wanted to write–and, more specifically, the articles I wanted to read. If no one else reads them, tough luck. Their loss!

---

This week's post is different from the usual Python article. It's a more personal essay to mark this arbitrary milestone and reflect on the past, present, and future–in no particular order. If this is not your thing, you can skip this week's post–I won't be offended. Normal service resumes in the next article.

---

April 2024

That's now. Today. The Python Coding Stack is twelve months old, and guess what? It turns out I'm not its only reader. Who'd have thought?! Others seem to enjoy reading the stuff I write every week. I no longer share vanity stats as any enjoyment and learning an individual reader gets is not correlated with how many others read and enjoy it. But I can say that I'd never have expected so many to want to read my thoughts and perspectives about Python.

April 2015

I taught my first Python student in April 2015. It was my first official step into a new career. I'll tell you about my old one later as it's relevant to my technical writing journey. But not yet. In the months leading to the first student, I knew I wanted to teach programming in Python in a style that I like, with a focus on understanding how all the cogs fit into each other and with an emphasis on visualising what's happening to take the edge off the abstract parts of the subject (that's most of it.)

I had never taught Python, but I had plenty of experience teaching technical subjects. I knew I loved to teach. And I knew I was good at it. I had evidence of this from my previous career. This meant I had the exuberant and slightly foolish confidence needed to get past the first step in a brand-new career. I taught adults and children in that first month. And I never stopped teaching either age group.

July 2020

By now, I had spent over five years teaching Python, but none of my work was in the public domain. All my teaching was with private students and in corporate training programs.

It was time to change this.

What's the easiest way to change this? Forget that. Let's go for the toughest way instead. Real Python, probably the foremost Python website then and now, was looking for guest authors. I had never written anything in public. I had never done anything at all in public in the Python world. But I applied anyway and got myself a pilot article.

My first public article went live later that year.

And I've been writing guest articles for Real Python ever since that day.

June 1994

Let's travel a bit further back in time. This was the end of secondary school and the end of my formal education in writing and the English language. This was the point at which I chose the science path and walked away from the arts and languages. They're not needed in the science world, right?

How wrong I was. But I didn't realise this for a while. As I made my way through the next ten years of my education, I narrowed further on science: first, two years of sixth form–they're the two years before university–where I studied physics, maths, and chemistry; then my undergraduate degree where I kept physics and maths; and eventually a PhD in physics.

I gave talks and wrote reports, articles, and theses in those years. But they were all in sciencese, not English. Scientists communicating with other scientists don't need "English English"; "Science English" is enough, right?

The answer to that question is not relevant to this story–this is a journey that doesn't lead to the siloed communication among scientists. But for the record, I think even academic scientific forms of communication ought to change from the current practices. But I digress.

March 2022

Let's travel forward in time again. By now, you realised I'm not following a chronological order. In March 2022, I decided to step even further into the public domain. I had been writing articles for Real Python and on my own blog, but they were all one-offs. It was time to start publishing more regularly. The platform that worked for me was Twitter, as it was called then. I made most of my friends in the Python community on that platform.

My "Early Twitter Era" (circa March 2022-April 2023) was critical in how I developed my communication style. Firstly, Twitter wasn't constrained by "old style" communication. So, I felt I had permission to experiment and deviate from the standards. Twitter forces you to do this since no one wants boring tweets. But I wasn't experimenting for Twitter's sake. At this stage, I was ready to deviate more and more from the classic style. And Twitter was the place to do it.

And people liked it.

February 2004

I published my PhD thesis in February 2004. This is relevant not just because it marked the end of my formal education. The months it took to write the thesis–the actual writing and not the research work itself–were the first time I became aware that I enjoy writing. I'm one of a small number of people I know who enjoyed the writing stage of their PhD thesis.

I was not in a position to deviate much from conventional writing–my PhD depended on this thesis! But it was the first time I felt I could and wanted to inject some originality into my writing. It was the first time I became aware that I could express complex concepts clearly. Of course, as with most PhD theses, very few people read the whole text. But writing it was the first step in a long journey that led me to where I am now.

And as a side note, I spent way too much time formatting my PhD thesis to make it look good. I've always been particular about all the small details that make a published text look professional, which enrich the reader's experience. And I think this matters.

March 2024

Let's get back to recent history. Last month, I published my first book, The Python Coding Book. But before talking about this book, let me talk about another unpublished one from my academic past. I'll return to the March 2024 entry later.

September 2006

I had just been appointed to my academic post at a London university, and I started lecturing for the first time in September 2006. I would have described myself as a shy person at the time. So the prospect of standing in front of 120 mostly-eighteen-year-olds wasn't appealing at first. And the first year of teaching wasn't great. But I learnt a lot, and I soon discovered the right mindset I needed to stand and perform for 50 minutes in front of students. I don't mean perform in the sing-and-dance sense. But I felt then, and still do now, that lecturing is a performance, requiring a slightly different version of my normal self. I wish I had taken some drama classes at school. I still think I should now!

Recall when I thought I was leaving the arts and languages for good when I focused on the science route? I was wrong! Science and technology rely on good communication. We need to communicate effectively with peers, newcomers to the field, and the general public. Some of the best communicators are fiction authors and actors. We need skills from the arts and language studies to communicate effectively.

So, I felt that I could get "in character" when entering a lecture hall. I didn't have to portray a significantly different character. Instead, I was acting as a slightly modified version of my private self. And it didn't take too long for my students to start voting for me for the lecturer of the year award!

I was teaching optics to optometry students–that's physics to clinicians. Standard physics textbooks weren't suitable. I also developed my own narratives and perspectives to teach my subject to my audience. So, I started writing notes for my students to compliment my lectures–especially since I soon reduced the amount of slides I used in lectures and the amount of text on them. The notes grew, and I refined them in both content and presentation. Soon, I had a book-like PDF document, which I made available to my students. This was their textbook. It was my first book.

I regret never looking for ways to publish it.

These years of developing and refining my teaching and writing styles were so important. I had constant feedback from my students. I knew what they understood and what they didn't. I could tell which analogies and perspectives worked and which ones didn't. I didn't teach Python in those years. (I didn't even use Python since MATLAB was the language I used throughout my science career). But those years teaching optics to optometry students helped me develop my communication style and to do things my own way. I honed my skills in explaining complex topics clearly. And as I was teaching a physics topic to non-physics students, the bar was high!

March 2024 (continued)

Back to March 2024, when I finally became a published author. In fact, most of the work on The Python Coding Book happened several years earlier. It started as notes I wrote for students in my Python corporate training courses. These notes grew over the years. I perfected them, refined the narratives and perspectives I used to explain Python coding concepts, and improved the analogies. Eventually, I also tidied up the formatting since I'm quite particular about how things look, down to the minute details.

I'm sure I don't need to point out the parallel with my optics for optometry students textbook. But I didn't want to make the same mistake and regret not publishing this book. So, a few years ago, I decided to take the first step towards publication by re-writing and editing my notes and releasing them online, one chapter at a time. The main reason I was publishing these online was to keep me accountable. I didn't give the online publication much thought as my real aim was to publish the finished book once it was complete.

I even didn't bother with coming up with a proper name for the website I set up. I had been referring to the book I wanted to write as the "python book". Very unimaginative but quite descriptive. I felt I should add the word "programming" or "coding" in it to publish online to avoid anyone looking for information about their pet snake. And, more out of jest than anything else, I added the definite article "The" and set up thepythoncodingbook.com in 2021.

I added chapters bit by bit. A few people started finding it and reading it, but my intention wasn't to gain an audience for this online version of the book but just to get the chapters out there for my own sake. If I wanted to promote this online version of the book, I wouldn't have chosen a name that made it impossible for a newcomer with a new website to compete in the SEO battleground!

Several months after setting up the site, I decided to start writing some blog posts about Python. At this stage, I had only published articles on Real Python, but I now wanted to write articles to publish directly. This would give me the freedom to experiment and write in my own style. I already had a website at thepythoncodingbook.com. So, rather than setting up a new one for the blog, I decided to use the same site.

This is when I truly started experimenting with storytelling techniques and deviating from the traditional templates for technical articles and tutorials. Technical articles should be fun to write and read, and humans engage much better with narratives rather than facts. We understand and recall things better if we can visualise them.

And I had a few articles that eventually picked up pace and went viral. My most read article remains to this day the rather niche How to Create Any Image Using Only Sine Functions | 2D Fourier Transform in Python. Soon, Google and other search engines decided to start serving this article to anyone looking for "2D Fourier transform python" and eventually to simpler terms such as "2D Fourier transform" or "Fourier transform python".

And this brought traffic not just to this article but to the whole site. So more people started reading the online book. More people started enjoying it, recommending it (several universities recommended this online book to their students), and sending positive feedback.

And by accident, it seems that my temporary working title, The Python Coding Book, hit the jackpot in the SEO lottery, too. Google now puts thepythoncodingbook.com at the top of organic spots when people search for "python book". How on Earth did that happen? I still have no idea.

The working title stuck. The book I published last month is called The Python Coding Book–yes, with the definite article "The", which I had added as a joke at the time! This also gave rise to "The Python Coding…" brand, which now includes The Python Coding Stack–this substack–and The Python Coding Place.

April 2023

The final step in this back-and-forth time-travelling journey is twelve months ago. The "Early Twitter Era" ended sometime in April 2023, when algorithm changes meant that it wasn't worth putting so much effort into crafting learning content for Twitter. It's a shame, really, but every cloud has a silver lining, as the cliché goes.

By this stage, I was all-in on sharing my visions and perspectives on Python with a worldwide audience. And I was also all-in on a new style of communication: more narrative, borrowing techniques from storytelling and adapting them to technical writing, using language as a tool to convey the message effectively rather than merely as a carrier of information.

I shifted my focus to a new platform: Substack. And I could now experiment with long-form articles instead of just Twitter threads.

If you're a regular reader of The Python Coding Stack, you've seen a mix of nearly traditional articles and some rather unconventional posts in this past year.

Breaking the Rules

Over the many years of my technical writing journey, I shifted how I write significantly. The initial drive was based on my personal preferences. I've always liked to visualise things and look for analogies to help me understand abstract concepts. I recall pacing up and down while studying undergraduate physics, trying to create a vision in my head of what was going on.

But then I started reading more about communication in general. Stories have always been central to humans. We've always communicated through stories. We even create stories when we dream as the brain processes the stuff we learn during the day.

But this post is not an essay about narrative technical writing or my vision of the brand of technical writing that works for me and that I think works well in general. I've been thinking and reading a lot about this topic. This substack contains the implementation of my views on technical writing. But I've also been writing a bit about narrative technical writing itself. I have another substack called Breaking the Rules, where I write my musings and thoughts about borrowing techniques from storytelling to improve technical writing. I've kept the theory and practice of narrative technical writing separate: The Python Coding Stack is the practice while Breaking the Rules is the theory! And I also have other plans to share my views about technical writing. But this is neither the post nor the publication.

May 2024 –

This post is about this publication. I'll keep writing, experimenting, pushing the boundaries of what a technical article can and should look like. I'll get it right sometimes and wrong at other times.

I want to reach as many people as possible with these articles. All articles are free for the first six months, and I want to have fewer articles behind the paywall, eventually perhaps none at all.

I recently made the shift towards focusing all of my time and activity on teaching and writing about Python. So, for those who want more than these written articles and who want to support an independent educator, there are paid services I offer! They support this publication–nothing is free in life, after all! So don't shy away from becoming a paid subscriber on this substack, joining as a member of The Python Coding Place for the full experience, buying a book (more titles coming out soon), or booking me for corporate training for your team. I prefer to focus on teaching and writing about Python rather than marketing. Still, I need to market my paid services to make sure I can keep doing this and doing more of it. So, I hope you forgive me for adding this last paragraph to an otherwise advert-free post about my past, present, and future teaching and writing about Python.

Time to blow out the single candle on the celebratory cake. Onwards to the second birthday and beyond.