It Takes a Village: Creating the TYPO3 Guidebook
Channeling community knowledge and experience into an open source technology book was a privilege and a lot of hard work. We think the result was worth it. Yes, we’d probably do it again :-)
The TYPO3 Guidebook is unique among technology books that I am aware of. It goes beyond specific coding nuts and bolts and takes a holistic perspective on using a CMS in an agency. It doesn’t just show you how to set up your first website, but that’s there, too! It also explains to the reader what TYPO3 is and some of the great selling points of the system. We included sections and chapters on how to:
- Start a business using TYPO3 CMS
- Meet and interface with the open source community
- Get involved in work and contribution that can improve your TYPO3 skills
- Get the most out of TYPO3 as the professional content management system that it is.
What’s between the covers?
The book is for TYPO3 and web development beginners — technical and non-technical. The book’s first half is a "deep orientation" in and around TYPO3, designing and building for the web, and how the open source community works. We think it could be valuable to students or career changers looking for a technical career and people (project managers, for example) working with web development teams. Furthermore, suppose you need to make business decisions about choosing an open source technology for your agency business or as a site owner. In that case, we think we’ve presented valuable, objective information.
When you include the second half of the book — a series of practical tutorials around building features and extending TYPO3, a security best-practices guide, and more — it becomes a helpful orientation for more experienced web professionals (developers et al.) who need or want to jump into working with TYPO3.
Guidebook Origin Story
In 2018, I took part in conversations about growing TYPO3 use and community beyond its strongholds in Central Europe. Alongside the suggestions that have turned into things like the mentoring program and international expansion activities in Africa, it came up that a book with a big name tech publisher would be a great marketing tool. And there hadn’t been a TYPO3 book in English aimed at beginners for a decade or more. At my company, Open Strategy Partners GmbH, we worked on a budget proposal for the TYPO3 Association and ended up with the commission to create a book and land it with a publisher. We thought we’d need maybe six months to get it all done … how innocent we were! Something like three years later, the TYPO3 Guidebook was available in stores and online.
We were lucky to have Heather McNamee on our team, a qualified and experienced educator. She was our guiding light when it came to shaping the content and organization of the final product. Working from the idea of creating something for beginners, we centered on a few fundamental concepts that would shape the book:
- Not just for coders. Not just technical information.
- "Open many doors" into TYPO3 and provide orientation and learning paths for various people with differing goals.
- We are not the experts; the community is. We decided it was our responsibility to channel the TYPO3 Community’s experience into a consumable form.
Channeling a Community
The vibrant professional community around TYPO3 has been caring for TYPO3 CMS, working with it, and constantly improving it for 20+ years. The community is the richest, most valuable source of context, priority, and experience, and we took on the role of facilitators. We made it our job to collect and refine this resource.
We conducted many many hours of interviews, collected feedback on draft after draft, and a book began to emerge. In parallel, we learned how to write proposals for publishing houses, had a few false starts, and tried many things, learning many lessons about what not to do in a book project! The writing itself wasn’t "difficult" per se. Our publisher, Apress, gave us helpful formatting guidelines and made sure we fulfilled their needs so that we would end up with a publication-worthy book. Getting the proper scope and depth for the many vital topics we covered was a big challenge. Defining the structure and sorting out where everything should go took a lot of thinking. Choosing which ten tutorials to include, balancing technical and less technical information (which I think sets the book apart from many others), and making it useful for different kinds of people was another enormous mountain to climb. Luckily, we were not on our own. We had the community and some expert friends and sparring partners to help us put it all together. We got help testing it all, and (this was a HUGE one) when there was more than one accepted way to solve a given technical need, our expert friends helped us make, test, and defend informed opinionated choices.
Thank you, TYPO3
Of the three authors on the book’s cover, two of us are quite active in the TYPO3 community as of 2021. The lead author and project guinea pig, Felicity Brand, is engaged in the TYPO3 Documentation Team, helps out behind the scenes on community content, and more! She is wonderful, living proof of the power of a welcoming community taking care of a great open source technology. She went "from zero to hero" during the two-year plus project, starting as an experienced technical writer with no previous experience of the web or open source. Now, she is something of a TYPO3 expert and a deeply passionate advocate and contributor! I have the privilege of hosting Application, the TYPO3 Community Podcast. I have taken it upon myself to help our community get to know each other better. At the time of this interview, we’ve published more than 20 conversations in audio and video formats, and my wish list of guests is still very, very long! I’m looking forward to doing many more episodes :-)
For me, the most important part of the book to get right was thanking everyone involved. If you own the book, take the time to see how many people helped make the project possible and as good as it is. Thanks again to everyone, and apologies again to anyone we inadvertently left out. Any mistakes and weaknesses in the book rest entirely on our (the authors’) shoulders, first and foremost, mine.
We’ve had positive feedback from readers who have validated many of our hopes and proven the Guide’s usefulness. For me, the results also demonstrate the value of the model we chose: Facilitating an open source community’s collective knowledge and experience.
About the author
Jeffrey A. "jam" McGuire, Partner at Open Strategy Partners, helps organizations communicate and grow at the intersection of open source software, business, and culture. He connects the value and people behind the technologies to the people who need to know about them through inspiring conversations, keynotes, podcasts, and more.
His approach to technology marketing—sharing the human context of complex technology solutions, and celebrating the expertise and success of their creators—has left its mark in business and open source communities over the last 15+ years.
Open Strategy Partners helps you communicate the value of what you do to connect you with the people who need to know about it, and help you grow.
Image Credits: Community green wall photo by Daniel Funes Fuentes.
ANTE, the OSP editorial code. Podcast 10
In this quick podcast, we discuss being clear about what you’re referring to in your writing with the editing code ANTE. There can be long rhetorical distances between whatever we’re talking about and the next “this, “that,” or “they” referring to it…More
Build a Product Adoption Strategy on Technical Truth
Creating a groundbreaking technology or feature is only the beginning. Product owners, founders, and builders often overlook the equal challenge of clearly communicating its value.More
Team Success: Flow and Productivity
Consistent productivity is essential for so many of us. A flow state helps. Here are some tips that work for us when we need that flow to happen.More