2020 was an interesting year, I’m sure you would agree.
Interesting perhaps in the way that inspired the cloaked curse “may you live in interesting times“.
Along with all that other interesting stuff, it was also a significant year for me in that it was in November 2020 that I decided to say “yes” when propositioned to write a book about my primary occupational skill which is PHP.
I suppose writing a book had always been something I knew I could do, perhaps even aspired to do, but I was also fearful of how much work could be involved.
There’s something special about writing a book, even in this modern age of low attention span media. I’m an avid reader and fully appreciate that the level of immersion and focus that you can get when reading good book can easily surpass other media.
I hoped that I could distil my years of PHP experience into something useful for both the up-and-coming generation of developers and also those, like me, who have been at this game for a while and need to stay up to date.
Deciding What to Write About
So I’d decided to write a book about PHP. But I only had so many pages to work with (not that you have any idea how many pages a subject needs at this stage). I had to decide on the structure and content of the book.
My book was to be in three parts of four chapters each. I eagerly added subjects to this and put together the most awesome set of subject matter that would take the reader from the basics all the way through to advanced productivity and design skills that would see them operating at a senior level.
Each section has a title and a basic summary and then each chapter in the section also has a title, summary and some bullets to describe what will be covered.
The plan was beautiful and the book was going to be amazing.
Technical Reviewer and Focus Group
When writing a book like this, you need a trusty sidekick to back you up with technical review. This is someone who knows the subject matter well and can help to proof read and confirm that the content is technically and functionally correct. This has clear parallels with the common practice of having code submissions go through a tech review process before being accepted as changes within a code project.
I turned to the very lively and friendly r/php group on reddit.com and made this post asking for a volunteer.
The response was quite massive and so I was able to not only find an excellent tech reviewer in Zach Stein, but was able to pull together a small group of people from across the globe to act as my “focus group”. I set up a Slack channel and bounced ideas and questions off them as I tried to put together the plan and wrote the book.
Zach and I were in frequent conversation. The fact that he was in the states and the way the time zones worked out was actually really good as my late evening writing sessions correlated with him being online and able to chat.
Starting to Write the Book
I started writing chapter 1. This was to be a fairly entry level round up of PHP fundamentals. The target page length for each chapter was around 20-30 pages.
My first chapter quickly gained in excess of 60 pages. The second chapter, about the same again if not more.
The book was on it’s way to becoming one of those unwieldy behemoth programming books that are impossible to hold without developing RSI, never mind enjoying actually reading cover to cover. I didn’t want that, and the publishers certainly didn’t – they knew the sweet spot and were keen to keep the page count under control.
All of a sudden, all the anxiety about having to write so much content switched completely to a growing realisation that it was going to be very hard, if not impossible, to cover the subject matter in the way I wanted to whilst squeezing it into the page limit. It turned out I had underestimated the page count requirement by around 300%.
The Big Refactor
At this point, I had some long discussions with the publishing team and we agreed to completely throw out the old book plan and restructure things completely so that we could produce a leaner, more focused and more reader friendly book. This meant lots of difficult choices on which content to exclude, but the outcome was a much more cohesive book that gave me the space to properly discuss topics in the level of detail that I wanted.
The Lazy Programmer
So one thing good programmers have in common is that they are basically lazy and hate doing things manually when they could be automated. It’s a mindset that develops quickly when you realise that boring stuff can be replaced by fun stuff (automating the boring stuff).
One thing that you need to do when writing a book like this is to embed code within your text. However, you need to be damn sure the code works correctly. This could present you with the challenge of copying and pasting code too and fro and generally faffing about and no doubt making mistakes that meant the book content becomes incorrect or inaccurate.
So I decided to solve this problem by writing a little utility that would allow me to automatically embed the code within the text of the book. Thus the inspiringly named php-book-markdown-tools library was born.
What this library did was allow me to write and run my code like a normal developer, tracked in Git, with a QA system and using Composer for dependencies.
I could then embed that code within the book by using a special markdown link, like this:
[Code Snippet](./../../../path/to/src/file.php)
```php
```Then I ran the processMarkdown command and, hey presto, the contents of the PHP file were embedded within the markdown code block. Not only that, but if I updated the contents of the PHP file and re ran the tool, the contents in the markdown block would be updated with the latest version.
Like many projects like this, the thing grew arms and legs and soon had all kinds of functionality including not only embedding the code, but also optionally running the code and grabbing the output.
This tool saved me serious amounts of time and gave me a lot of confidence in the code. I recommend any other aspiring authors check it out as I can’t say I’m aware of anything else that solves the particular problem it solves. I will admit though that it needs some better documentation – pull request gratefully received!
The Build Process
I wrote the book in Markdown which is a lovely text format that is very easy to read and write and also ripe for automation. It is very well supported by my IDE which is pretty important for this kind of book I think.
The publishers needed the book to be in docx format however. I run Fedora Linux on the desktop so I simply can’t (won’t) run Microsoft Word and so I needed to find a solution.
I created a build script that handled the whole process, which you can see here:
#!/usr/bin/env bash
set -eEou pipefail
readonly dir=$(dirname "$(readlink -f "$0")")
readonly projectRoot="$(dirname "$dir")/"
readonly codeRepoUrl='https://github.com/PacktPublishing/The-Art-of-Modern-PHP-8/blob/main/'
readonly codeLocalRoot="$(realpath "$(dirname "$projectRoot")"/php-book-code/)"
readonly chaptersDir="$projectRoot/chapters"
readonly chaptersProcessedDir="${chaptersDir}-processed"
readonly docsOutputDir="$projectRoot/docxConverted"
readonly referenceDocPath="$projectRoot/pandoc/reference.docx"
readonly columnWidth=92
readonly highlightStyle="kate"
readonly fileNameSuffix="$(date -I)"
echo "
Spell Checker
"
bash $dir/spellCheck.bash
echo "
Confirm Code Repo Valid
"
phpVersion="$(php -v | grep -Po '(?<=PHP )[0-9.]{3}')"
if [[ "8.1" != "$phpVersion" ]]; then
(cd "$codeLocalRoot" && ./bin/qa)
else
echo "
SKIPPING QA WHEN RUNNING PHP 8.1
"
fi
echo "
Update Code Snippets
"
bash $dir/updateCodeSnippets.bash
echo "
Copying Chapters into $chaptersProcessedDir
"
rm -rf "${chaptersProcessedDir:?}"
(cd "$projectRoot" && cp -r "$(basename "$chaptersDir")" "$(basename "$chaptersProcessedDir")")
echo "
Cleaning up Document Directory $docsOutputDir
"
rm -rf "${docsOutputDir:?}"
mkdir -p "$docsOutputDir"
echo "
Preprocessing Markdown
"
php -f $projectRoot/vendor/lts/php-book-markdown-tools/bin/prepMarkdownForConversion \
"$codeRepoUrl" "$codeLocalRoot" "$chaptersProcessedDir"
shopt -s globstar nullglob
echo "
Converting Markdown to Documents
"
for f in "$chaptersProcessedDir"/*/*.md; do
mdFilename="$(basename "$f")"
mdFileDir="$(dirname $f)"
echo "
STARTING $mdFilename
($mdFileDir)
"
# need to run pandoc in same dir as doc for images to work
cd "$mdFileDir"
docxFilename="${mdFilename%.md}.${fileNameSuffix}.docx"
echo "Creating $docxFilename"
pandoc \
--fail-if-warnings \
--highlight-style "$highlightStyle" \
--reference-doc "$referenceDocPath" \
--columns "$columnWidth" \
-o "$docsOutputDir/$docxFilename" \
"$mdFilename"
echo "done.."
echo "
DONE $mdFilename
($mdFileDir)
"
done
echo "
ALL DONE
"This script firstly runs the full QA suite in the code repo (unless working in PHP 8.1 which is still not release and so QA tools don’t support it).
Then it runs the process to update the markdown files with the latest changes in the code repo, running and capturing output for any code snippets where we wanted to do that.
The next step is to copy all these markdown files into a staging folder for further processing. The extra processing step is where all the terminal images were created and the special format code snippet links were converted to GitHub links.
Once we had the fully processed markdown, we needed to convert it into docx files that the publishers could work with. For this I used a great tool called Pandoc – highly recommend if you have the misfortune to need to create docx files!
The Editing and Review Process
Writing the content of each chapter is only the beginning. There is also a vitally important tech review stage where the content is assessed for technical correctness and many discussions were had and tweaks made to improve clarity, include extra information or to correct any mistakes.
The content also needs to be adjusted for grammar and style and generally tidied up as text. There was a difficult chicken/egg situation that developed as the book was being written in Markdown, a fundamental requirement for the automated code embedding, however the proof reading and style tweaking was done in Microsoft Word and so the markdown had to be converted.
Thankfully we agreed a process that allowed the tech review stage to be done whilst the book was still in Markdown format and then the content edits were done subsequent to that. This does have the disadvantage that content/style edits are not updated within the Markdown files. I’ll tackle that when it’s time to release another edition. With a bit of luck I’ll find an automated solution because it sounds like a tedious task to manually cross check and update the Markdown with changes within the docx files.
Foreword
At this stage of the process, you need to find someone to write the foreword for your book. Ideally this is some kind of celebrity figure who will bestow esteem and kudos onto your lowly offering.
I only really know one person who fit that bill and so sent a message on Twitter to Lorna Jane Mitchell who I have known for a long time having originally met at our local PHP user group meetings. She very kindly was able to spare a bit of time in between her busy conference speaking schedule to throw a few words together – the cherry on the top.
Final Proof
Once the whole book is written, reviewed and updated, it goes in for final proof. This is where the docx format is converted by the publisher into PDF files that have all their fancy styling etc applied and is generally prepared for actual printing.
This stage is pretty boring to be honest as there are niggles that creep in and you have to read the whole thing through again to make sure that its all correct.
I’ll admit that by the end of this stage, I would have been happy to never lay eyes on the text of this book again. But it’s all worth it of course because…
The Publication
The book gets published. First it goes on pre-release on Amazon for a bit and then once it’s all printed and ready to be sold then it goes live. This is the stage where you can start to tell the world about it and hopefully sell a few copies and maybe earn a little bit of cash. I’m not really expecting this book to be on any best seller lists, but it will always have a special place in my heart as the first book I wrote and one that I am actually quite proud of.
The Plug
Of course, I have to throw a little plug in there. With a bit of luck this epic tail has piqued your interest and you are ready and eager to invest some of your hard earned cash into a copy of this book!
Also on Amazon