Content Creation Process

Ever since I started the process of writing a book I have had to work on streamlining the content creation part a bit! For articles on my personal website, I usually write and post when I have something the share. Usually these are simply articles conveying my thoughts or small tutorials focussing on a very specific topic. For the book Building Real-world Web Applications with Vue.js however, I have had discover a new process.

It started with determining the outline of the book with all the topics we wanted to cover and address. That structure really helped in getting the scope for each chapter right as I've discovered. Scope creep is a real thing, when you want to teach and deliver well rounded projects!

After finishing the drafts of the first eight chapters, I sort of settled on a way of working. This method works for me, it's not necessarily the best for everyone, but I thought to share it anyway.

The book is about Vue.js projects, so every chapter builds a self contained project with a wide variety of topics. When I start on a new chapter, I first take a look at the teaching goals we've set out for that particular section, to refresh my memory on the concept I had in mind.

Well prepared

I start by building the app with all of the required features as sort of a prototype. I will inevitably refactor parts during the build and move bits around to make it work. If the topic covers tech that I'm not familiar with, I am constantly looking up the documentation of that library or tooling, in order to follow (and in turn pass on) the best practices.

Sometimes, when I need to cut some corners due to limiting complexity, it might mean I have to build a custom implementation or wrapper around a library. I'd prefer to prevent it, since it paints a less realistic picture of what a production ready project would use, but sometimes you have to make due.

While building, I have a Notion document per chapter, where I take my notes: installation steps, decisions during the process. Everything I think I'll need in order to reproduce my building steps when writing the content. I aim to deliver the software at full feature completeness, but do have some leeway when defining the types or formatting and structuring code. Building the project once helps me in breaking it down into smaller, logical steps. (I note those down as well).

Software or Process?

I've noticed a common pitfall here. Normally, when you're building software, you don't build the perfect solution from scratch. You build something, test it out, optimise it. Then you add another feature, leading into more refactoring of existing code. When teaching, it's a balancing act between teaching the process of creating software, with revisiting and refactoring existing code, or sharing the final solution.

Depending on the topic, I choose what parts to highlight from both process as well as the solution. I certainly don't want to convey the idea that everybody writes optimal, well structured code out of the gate!

Creator mode on!

Once the initial project is done I can start creating the chapter. This time I use the example code to rebuild the solution from scratch while documenting every step. I don't have a strict plan when doing this, but I do focus on delivering code that runs without errors after each step. This means you should be able to follow along and verify every step by running the code with a bit more confidence. This approach might mean that I sometimes have to scaffold out stubs or mocks for certain bits, which I later have to revisit. That's not necessarily how I would write the code, but being able to validate each step is a bit more important in this case. I think.

Lessons learned!

I've learnt that big code blocks can be very challenging to explain. Sometimes you need to include a feature in big chunks. Bear in mind that at this point, the reader will have some experience using a particular tech stack. My approach is to write as readable code as possible (trying to adopt Clean Code as much as possible) and add comments that connect the reading material to certain features in code. In the chapter, I refer and highlight the important sections to explain what's going on there.

Using the feedback from tech reviewers, I've also realised the value of screenshots! At some milestones during a build, it can be very reassuring to provide a snapshot of the current (expected) outcome. Additionally to screenshots, I started to incrementally push code to the public code repository that I reference each chapter.

Thoughts on the process

At this point, I think I've gotten the hang of writing these sort of contents. I knew it would be very labour intensive and it is. Part of the efforts is in familiarising myself with different techniques which I rarely use in my day to day activities, which helps me in understanding these concepts better as well!

I realise that what I'm building has limited longevity. Software changes and gets updated with, sometimes, introducing new concepts that change the best practice. This means future revisions! When I encounter those, I'll see what approach works best for those as well.

In my case, I'm creating content as reading material, but I imagine these step to be applicable to creating recordings as well. I would probably take the chapter notes as input steps for creating a video though. 😅

Who knows, maybe I'll do a video tutorial series at one point too!