heather mcnamee
What a wild ride these last few months have been! After the last update about the book we’ve wrapped up the illustrations, the hands-on guides, and the pieces that turn a piece of writing into a book such as front and back matter, references and a glossary. Writing a book is a challenging and demanding process. In this post, I want to share a bit about what has gone into creating the guides.
We’re excited to be another step along in the process, being able to celebrate handing the book over to our publishers, Apress.
Where Is the TYPO3 Guidebook At?
In the last update, I interviewed co-author Felicity Brand so you could know a bit about who is writing this book and what we are up to.
We talked about how the book is written in two parts.
- The first part contains four chapters that cover a showcase of what is possible with TYPO3, then a discussion about design, implementation, and maintenance.
- The second part contains ten practical guides with procedures to work through some common activities.
Here’s a bit about me, how I shaped the design of the guides, and how we created them with subject matter experts.
Pro-Tips on Making a Peanut Butter and Jelly Sandwich
I’ve been working in creating learning content since 1997 (gasp!); from language learning content, to games, to classroom and e-learning materials. But my very first experience in instructional design was writing steps for making a peanut butter and jelly sandwich when I was around 9 years old. As part of the fun, our teacher got up and attempted to follow our steps. She acted it all out, with real bread, and peanut butter and jelly—it was so funny!
I recall being shocked at the results of not explaining how to get the bag open, assuming something like that was totally obvious. We all refined our procedures, and learned how important the details were. I recall adding a tip about pulling the best bread from the centre of the loaf. Pro-tips.
Little did I know that it would be my first such writing exercise that would lead me to a Masters in learning and technology, and creating hundreds of hours of learning materials, tutorials, elearning, screencasts, and now… collaborating on a book!
What I love about working on this kind of content is being able to listen to subject matter experts, and distil what they know in a way that is comprehensible to newcomers.
How the Guides Are Designed
One thing I always find frustrating about tutorials is that they either assume too much prior knowledge or they spend so much time in meandering details that could be summarized, or referenced as prerequisites. So the experience is either “you lost me” or “get to the point.”
That’s why each guide starts by discussing the why and then moves into the step-by-step how.
- First, we set the stage with the scenario or problem to solve. For example, there’s a guide on creating an area on the site where premium content should only be available for logged-in users. Providing a scenario helps the reader understand the benefits in a real-world context.
- Next we establish the outcomes. This gives the reader a promise that at the end of the tutorial they would have specific tangible outcomes and learning outcomes.
- Then we explain the prerequisites. These might be assumed conditions or configurations. This reduces the need to explain everything because we can refer to other guides, or official documentation if needed.
- After that, the procedures are chunked into steps with numbered tasks.
- To help learners expand their newfound knowledge, we list out recommended next steps for readers to continue their learning journey.
Along the way, steps include “expected outcomes” so we can make sure people are on the right track. After creating and testing so much classroom learning material, I’ve always been surprised at just how lost learners can get. Having check-points along the way helps people know “If you don’t see that, you’re on the wrong track, turn back!”
Distilling Knowledge From Subject Matter Experts
The guides cover topics from installing, to extending, configuring and troubleshooting. We’ve even included a guide to help you make a business out of selling TYPO3.
We consulted with subject matter experts along the way, and each guide has undergone comprehensive technical reviews and testing.
Mathias Bolt Lesniak and Benni Mack determined the topics for the guides. There are many more topics and we hope to keep writing guides beyond the release of the book, to create a treasure trove of material for the community to use.
Of course, there is more than one way to do things with TYPO3, so the guides only present one method. Most of the guides also discuss “things to consider.” There’s always more than one way to do things, so we weigh pros and cons, and if it’s needed, we explain why we went with a certain approach. Usually it’s for the benefit of the first time learner to have a simple and clear practical exercise. We try to point users to other ways of doing things, best practice and alternative choice.
What Happens Next?
We’ve now handed all draft content over to Apress for the next series of steps in book production. We’re aiming to produce in hardcopy and ebook format. The next thing that happens is the production workflow which involves copyediting, proofreading, typesetting and layout.
