Ever since 2006, I have wanted to take a sabbatical. I wanted to take some time away from working on schedule-driven projects for my employer and do something for me instead. Why have I only wanted one since 2006? That’s a tale steeped in office politics and tech start-up financial drama. What I wanted to do during my sabbatical has varied, but it has always been more about writing (fact or fiction) or travelling than coding. The travel would have been a tour of India, to catch up with friends I met in Silicon Valley who have returned home. Fictional writing would have been purely for me, a complete shift away from work. Now I finally have the opportunity to take a sabbatical I have decided to try to write a book.
The book’s subject is close to my heart: debugging serial bus issues on small-footprint embedded systems. I have spent 30 years in the field and mentored many in their first forrays into I2C, RS-485, SPI and Modbus, to name a few. There is a lot I want to share, but in the first month of writing, I realized I would have to trim the scope to just one protocol and general debug processes. The revised scope is currently for a booklet or pocket guide.
Now that I’m 8 weeks into the project, it seems like a good time to audit my progress and plan the final month’s work. Let’s see where I’m up to.
The road to my sabbatical.
For some reason, I had only associated sabbaticals with academia, but I learnt in 2006 that this could happen in industry, too. At the time I had worked for seven years in one company and was into my sixth year with my second employer. It was a scrappy start-up that had been spun out from a larger tech company.
Though the company was seven years old, I joined early, but not at the beginning; it hadn’t taken time to adjust its vacation policy. We were still on 10 days of PTO (paid time off) at that point; nothing gained by seniority. Ever since I had joined, there had been a promise that “as the company matured”, they would fix the benefits for long-term employees.
It was a small company, oscillating between fifty and a hundred employees. Having the CEO or CFO stop by and say hi was not uncommon. Our CFO popped his head into my cube at the wrong time. I was in a bit of a grump at the time. I was low on PTO available, we’d just lost our boss, the general mood in the office was not too great, and I needed to get back to the UK to visit a sick parent (yes, I was living in California at that time). So, I gave my CFO an unfiltered account of the current SNAFU.
An hour later, the CFO was back saying that he and the relatively new CEO realized the error of their ways; at the next all-hands, a very good re-write of PTO and leave policy was announced. The new policy was in line with the rest of the industry, and we even earned a two-month sabbatical in our 7th year of service. The old hands all treated me very well that week.
So, my first sabbatical would have happened in 2007, but as luck would have it, we had a funding event that failed just before my 7th anniversary. I could have taken time immediately to work on a personal project, but that was my first redundancy, so I put immediate focus on employment.
The last sixteen years have not seen the stability of the first fourteen years of my professional life. I have never been anywhere long enough to earn a paid break of that size. I have also jumped from one small start-up to the next, and so I have not even been anywhere with a 20% project. I did spend a year in a team that had recently been acquired by a tech giant. The parent had allocated 20% of my time for growth and learning, but the product schedule demanded 110% of my time, so if I wanted to do any learning, it was to be on evenings and weekends. The perils of working on consumer products.
My last job had a DTO (discretionary time off) policy, and we were coming up on a major delivery; my work was pretty much done, and I was nearing four years with them. Naturally, I started discussing what my options for an extended break might actually be.
If you have seen a recent spike in my rate of delivery to this blog, well, that is because I am taking a break from my career. November, December and January are dedicated to working on my writing skills and taking on the challenge of trying to write “The Book” about debugging issues with serial protocols.
So, two months in, and I’m taking stock of where I am at relative to where I wanted to be. I took a long weekend to relax before starting in on what has been a 9-5 (more like 8-6, but sometimes a 9-noon) job. The first two days were to plan my time, and develop a schedule. What were my goals? To write a book. Where am I now? I have a book! It is better than another that I bought on Amazon, but that was autogenerated from a video presentation.
Writing? It’s something I do.
The book idea has been brooding for years, since 2015. It wasn’t until 2019 that I actually started. I would find an hour or two every few months when I could add to the knowledge base I needed as a foundation. Things faltered to a stop. I’d been collecting information on a Confluence wiki. It got to the point where I was getting “inactive account” notifications from Atlassian, and I finally let them archive it. I don’t believe that was any great loss. It all needed editing, collating, and even re-writing into a book form.
On day one of the current project, I wrote a manifesto for the book, the wiki and the blog. I would blog twice weekly; I mean, how hard can that be. I have lots of tech hints to share and lots of tales of adventures in the industry, also I am learning how to write, edit and publish a book. I would spend time researching and then time writing. I would also spend time running sample code to illustrate what I was talking about. Wiki articles would be brief essays based on the research, and the book would be a restructuring of blog and wiki content with unique content.
I have had personal blogs for years. I would happily post anything between 5 words and 5000. I would often have a photo alongside, or even, at times, just a photo. Spell checkers and grammar checkers stopped me from making too many mistakes. I would write in my voice, my dialect. A personal blog, to my mind, is a journal that you have shared, so it has an essential rawness.
I have written Wiki content for decades, well, since 2011 actually. Internal wiki pages can contain requirements, a plan of record, engineering notes, design, procedures, FAQs, policies and lessons learnt. Internal wikis are schizophrenic, taking on as many styles as contributors, to the point even paragraphs on the same page sound different. Up-to-date facts are the key. Clear procedures are essential. Spelling and grammar, as long as they don’t hurt the facts, are secondary.
I’ve come to learn what details are valued and what omissions are problematic. There is a skill to balancing what information is needed. Often, wikis are written very targetted for use within the team and can make assumptions on knowledge. They are just as often a form of cross-discipline information exchange, where everyday terms for one team need a detailed definition for another team. Wiki’s, unlike books, can easily link to supporting resources, like an internal glossary or more in-depth details that would otherwise clutter the current page.
You can imagine my surprise when I wrote my first blog post here this year and started running it through ChatGPT, looking for help on flow and readability. What I could knock out in twenty minutes for a personal blog, a similar-sized piece for this blog, took six hours. Then I sat on it for 24 hours and re-read before scheduling the post rather than going live immediately.
The book’s origin was an off-the-cuff remark by my boss. ”If anyone could write the book on debugging low level serial protocol, it would be Alex”. A younger colleague, a software engineer, was looking for help with an issue talking between two nodes in our camera system and wanted to know who could assist. I’d already been documenting procedures on our corporate wiki for set-up and configuration procedures. Embedded system debugging was something I’d been doing for years, learning from mentors as I went, and keeping my paper notebook updated. No one had wikis in the 1990s. I hadn’t really thought about documenting debug flow on the wiki in later years, but I did start to see I was mentoring more and more team members. Every debug was unique in the result, but the methods were common, they could be recorded.
After a few more career transitions I realized that I was leaving so much engineering general knowledge behind. Sure, I can’t move the trade secrets to a personal wiki, but I could track the non-proprietary information. That was the genesis of this blog and website. The next logical step seemed to be to try to write the book.
Setting the scope for the book.
Very early on I realized that I could not write a full textbook in 3 months. I could write a pocket guide. I am very fond of a series of notebooks that were written by Forest Mimms and published by Radio Shack. These little guides to electronics were only 120 pages long and notebook-sized. Surely, I could do that.
An early metric I had was that three months is about 12 weeks. 12 chapters is a good size, so I need a chapter a week. Another metric was 120 pages, that is 10 pages a week, or two pages a day. Writing two pages a day? I’ve been writing this post for an hour now, and it is about 2 pages long already.
I’ve been writing – stream of consciousness. Grammarly was paused for an hour and just turned back on. I know it’s going to take half an hour to clean up grammar and careless typos. Then I’m going to fight Grammarly as it insists that I’ve waffled. Well, I want this as a waffly post today. I digress. The point is, yes I can spend two months researching and writing content, then I would also need about a month to edit, illustrate, and add code samples and scope traces. So I do have the time needed.
So, what do I put in the book? Well, it’s not everything that I initially wanted. I wanted to leave the reader well-informed about any serial bus they may encounter. Having not used all the busses and protocols out there I would drop the ones I didn’t know. I’ve lightly touched MIPI and PCIE in the past. I’ve forgotten everything I knew about SCSI. I still have yet to use I3C, and only just started CAN recently.
The ones I wanted to touch on first were I2C, SPI, UART, EIA-232 and RS-485. That gives half duplex, open drain, synchronous and asynchronous busses with open-drain, push-pull, charge pumps, and differential drivers. We could then look beyond the bus, into event-driven and DMA (direct memory access) streamed interfaces.
Who will be the audience? Electronic engineers and embedded software engineers already know most of this information. I started as a software engineer, a computer science major, and had to learn the hardware on the job. Software engineers transitioning to embedded programming would be my target. This would limit the book’s scope as I could assume strong software development and debug skills and focus on showing the hardware observation skills and the idiosyncratic behaviour of these buses.
It’s obvious to me that a book, like any body of code, can be designed using a top-down functional decomposition method. Have you ever noticed how a mind map looks like a Warnier-Orr diagram? So, I used MindNode to plan out the chapter ordering of the book. Sections, chapters and subheadings revealed themselves.
In my first month working full-time on the project, I realized I had massively over-committed. I shifted my scope to the essential debugging skills and the example cases for I2C. I2C is ubiquitous in industry and is popular with hobbyists. It has enough weirdness to be challenging (open-drain, hung internal state machines, etc.). I have spent a lot of time integrating camera sensors and IMUs (inertial measurement units), which were I2C connected, so my experience there is strong and fresh. I2C is already well documented, but I2C debugging not so much.
The other protocols will have to be added over time. With the foundational format of a booklet about embedded system debugging using I2C as an example, I could later publish the same booklet with SPI for the case studies and then the others. Ultimately, an omnibus edition could appear.
Taking stock at eight weeks
I guess now that I have about 20 topics covered, running at about 100 pages of letter-sized paper, I have the booklet in its raw form. I need to now flip focus onto review and edit. I need to make sure the flow is correct and the content meaningful. I need to clean up the captures I have from my oscilloscope and force a few more problems to get more. I need to repeat some of the exercises with my logic analyzer.
The final step will be to share the results. I’ve been looking at how to do that. The simplest is to put the PDF on this page. I am still looking at other print-on-demand and e-pub options.
I made the claim earlier that my book is already better than some out there. That is because the bar for self-published works is apparently very low. I recently bought a book from Amazon, one of three by the same author, and the book seems to be an automated conversion of a YouTube video to book format. It is a speech-to-text conversion with no human review. The illustrations are downscaled screen captures, with the presenter window blacked out.
My content is rough and raw right now, but even so, it’s still better than such cheeky shenanigans. The text-to-speech caught all the pauses, every “eh”, “um”, and “ah”. If this wasn’t bad enough, I2C was spelt “eye-squared sea” at one point, showing a blind trust in the machine without human review. I am not sure the video creator knows that the book exists.
I like textbooks that have an easy conversational style, but I know I can waffle. I’ve been following style guides to make sure that I speak in an active voice. I have been making sure my content is lean enough to keep the readers’ interest but full enough to be meaningful and worthwhile. I can’t afford a publisher to review this pet project, and my friends are already overburdened at work, so I have leant into ChatGPT as a first level of review of style.
I am using the AI mostly for checking “readability”, but I have asked it to catch obvious factual errors. I know from trials early in 2023 that I could not trust ChatGPT with very specific domain knowledge, so I still fact-check. I even check things I have known for decades just in case I mislearnt or misremembered.
I have also been taking pains to make sure any diagrams are readable. Screen captures from my oscilloscope will suffer if the scaling is wrong when printing. I have generated diagrams as SVG (scalable vector graphic) files where possible, so they are cleanly rendedred. Bitmap images, such as PNG and JPEG, may have issues when scaling. They may show jaggies and anti-aliasing artifacts, often making text unreadable. As much as I’d love to use real captures as often as possible, I have been creating waveforms using WaveDrom and PlantUML. These idealized examples are for readability. There are some timing diagrams borrowed from data-sheets, which I intend to replace with my own diagrams, or I will seek permission to use the copied content.
I know the booklet won’t be perfect, but it will be usable. For self-published, a valiant effort will probably suffice. If I seek a publisher, this booklet would probably stand more as a portfolio example, a teaser of my potential skill. Having a real editor, a budget for peer review, and an illustrator would change the book, bringing a professional polish.
With such an aggressive schedule, it seems wrong to take time out for a holiday. The world slowed for the seasonal holidays, Christmas and New Year, and I slowed with it. The days were kinda broken too by some household needs and a few appointments that have taken several hours out of my work day. However, I’d just put in a very intense 4 months at work before taking a very serious sabbatical. I hear it’s healthy to take a break, so that’s what I did.
I have found that I really do enjoy the process of writing. Committing to the project as if it were a full-time job has enabled the project to be doable. Maybe at eight weeks I’m still in that wonderful honeymoon period, but I think I would enjoy a career switch to tech writing.
Though I have been writing for years, I still had to learn some new tools. I already write in Markdown for GitHub README.md files and wiki contributions, but there are limitations. LaTeX is another documentation language, and a subset of which can be embedded within Markdown. Converting Markdown to PDFs lead me to learn Pandoc, a useful tool. Managing the chapters in GitHub, each as a separate file, and wanting to bring them together as a whole led me to realize that Makefiles, mostly used for the compilation of code, have value in other disciplines. Every new skill goes on the resume and makes me more productive in my bread-and-butter roles as an embedded engineer and tech lead.
In the new year, I hope to get back to regular blog posts. I have new topics I want to write about, such as my experiences with Markdown, LaTeX, and Pandoc. I also want to revisit Grove dev kits, and I have a few new tools to review. I also want to talk about how ChatGPT and Grammarly have helped and hindered me on my voyage. I will be wrapping up the book. I’m not sure if that’s simply “putting my money where my mouth is” or “exorcising a daemon”, but it was a personal challenge I have been wanting to fulfil, and it has indeed been fulfilling.
I hope you will enjoy the future content of this site and find some useful information and insights.
Happy New Year
Alex
- This post was written with only basic spell-checking enabled. This took about an hour.
- Grammarly was used to check grammar and spelling after writing so as not to slow down creative flow. Grammar and spelling edits were swift.
- Grammarly rewording suggestions were mostly rejected; they took away my dialect and tone.
- Even though UK spelling is enabled, Grammarly doesn’t like “learnt” and “earnt”. I do, so there!
- ChatGPT assisted with a review of flow and narrative style. Additional paragraphs were added in response to the feedback. This was a 3 hour process.
- Dall-E was used for line art. Photos by me.
- Amazon links are affiliate links.
A note about the art from ChatGPT
Here is a conceptual banner image created by DALL-E for your blog post. It features a paper notebook with handwritten notes and sketches related to embedded systems and serial protocols, accompanied by a few technical tools like a pen, a logic analyzer, and a printed circuit board. The style is a simple 3-color line diagram, emphasizing clarity and a technical feel, which should align well with the themes of your post.
Glorified Plumbing 