Since embarking on the journey of crafting my book, "Building Real-world Web Applications with Vue.js", I've realised that writing educational content is an art in itself. 😅
While I've been accustomed to producing the occasional article for my personal website, which usually convey my musings or delve into specific topics, the task of creating a book called for a different approach.
Let me walk you through my process and share insights that could prove valuable to budding authors and educators.

The Crucial Role of Structure

The journey started with the creation of a well-structured outline for the book, encompassing all the topics we aimed to address. This outline turned out to be indispensable in keeping the scope of each chapter in check. Scope creep is real, especially when your goal is to teach and deliver comprehensive projects.

Once I had the initial drafts of the first chapters, I settled into a working methodology that suited me. While it may not be a one-size-fits-all solution, I believe it's worth sharing. I call this the "Works for Me Approach™"!

Given that the book is centered around Vue.js projects, each chapter revolves around constructing a self-contained project, encompassing a diverse range of topics. When initiating a new chapter, I revisit the teaching objectives to refresh my memory on the fundamental concepts I intended to convey.

A Methodical Approach

I kickstart the chapter by building the app as a prototype, complete with all the necessary features. Throughout this process, I inevitably find myself refactoring certain sections and making adjustments to ensure everything functions seamlessly. If the chapter contains technology I'm not entirely familiar with, I often will (and need to) refer to documentation to adopt best practices, ensuring I can pass on this knowledge accurately.

On occasion, due to constraints in complexity, I might need to develop custom implementations or wrappers around libraries. While I'd prefer to avoid such scenarios, they can become necessary to present a realistic picture of a production-ready project.

Throughout the development phase, I maintain a dedicated Notion document for each chapter, recording installation steps, decision points, and notes to replicate the building process when it comes to writing the content. My objective is to deliver the software with full feature completeness, but it doesn't have to be polished yet.

Balancing Software and Process

One common challenge I've encountered is explaining large code blocks. In typical software development, as we all know, you don't start with the perfect solution from scratch; you build, test, optimise, add new features and refactor all the time. When it comes to teaching, you're walking a tightrope between showcasing the process of software creation and sharing the final solution.

Depending on the topic, I decide which aspects to highlight from both the process and the solution. I believe it's important to not give the impression that everyone crafts optimal, well-structured code right from the outset.

Embracing Creator Mode

Once the initial project is complete, I transition into "creator mode". This involves utilising the example code to rebuild the solution from scratch while meticulously documenting each step. I don't adhere to a strict plan during this phase, but I ensure the code runs without errors after each step. This way, readers can follow along and verify their progress with confidence.

Lessons Learned and Future Revisions

Through this process, I've learned that teaching complex topics with extensive code blocks can be challenging. To mitigate this, I strive to write code that's as readable as possible, adhering to Clean Code principles, and augment it with comments that bridge the gap between the reading material and specific code features.

Additionally, I've come to appreciate the significance of screenshots and incremental code pushes to a public repository, which I reference in each chapter. These elements provide readers with visual clarity and a hands-on experience.

At this point, I feel more at ease in creating this type of content. While it's undoubtedly labor-intensive, it's also an opportunity to explore techniques beyond my daily routine, enhancing my comprehension of these concepts.

I'm fully aware that what I'm building has a limited shelf life. Software evolves, ushering in new concepts and best practices. This necessitates future revisions to keep the content aligned with the evolving landscape.

The Path Forward

In my case, I'm primarily creating written content, but I can envision these steps being equally applicable to the creation of video tutorials. If I were to embark on a video tutorial series, I'd likely utilise the chapter notes as a blueprint for crafting the videos.

Who knows, a video tutorial series might be on the horizon?

Writing this book has been an enriching journey, and my hope is that these insights will assist fellow educators and authors in their own endeavours.

Stay curious and continue sharing! 🖖