TYPO3 Book Report—Who’s Writing the TYPO3 Book?

Categories: Community , Association , TYPO3 CMS Created by heather mcnamee
Woman at lectern with projection screen showing hashtags open-source and community-help-wanted
Felicity Brand speaking at a Write the Docs meetup in February, 2020.
You might be wondering just who is writing the TYPO3 Guidebook and how the project is coming along. I sat down to interview my colleague Felicity Brand, the TYPO3 Guidebook main author, about her experience, what she’s working on right now, and what’s next on the horizon for the book. If you’d like to keep in touch, subscribe to the TYPO3 Guidebook mailing list and we’ll have some more news for you soon!

Sign Up to the TYPO3 Guidebook Mailing List

How did you get into technical writing, Felicity?

In my former life I was a business analyst, and I always enjoyed the writing aspect of that role. I wrote functional specs, tech specs, and user testing plans. 

I had studied English and loved writing, but technical writing was a new field to me. When I discovered technical writing was a thing you could do, I took a postgraduate course in Melbourne. 

I went through the course with a good set of lecturers, who were active in the technical writing community. That’s how I got started as a tech writer, and have been enjoying it ever since.

How did you get into open source?

As a technical writer, I had always worked in the corporate world, documenting software and attending conferences in the corporate world. I started hearing more and more about open source and didn’t understand it. 

Fast forward 12 years… and I had a baby and that was a catalyst to change my working life. I needed more control over my schedule and flexible work hours. One of the great things about working in open source is that there are a lot of opportunities to tailor your work-life balance. Even before the Covid-19 pandemic, remote work was common, and there is a lot of focus on the human side of technology, including staying happy and healthy.

I started with Open Strategy Partners, and coincidentally, at the same time I participated in the inaugural Google Season of Docs program. Since then, I joined the embryonic open source project for technical writing, The Good Docs, and I’m on the steering committee for that. 

Tell us about The Good Docs and the Google Season of Docs.

The idea with The Good Docs is to produce best-practice templates to help open source project maintainers produce their own documentation. My mentor from the Google Season of Docs was the driving force behind this idea. 

During the Season of Docs, I worked in an open source community focused on geospatial software. The Open Source Geospatial Foundation (OSGeo) is an umbrella for a large number of separate OSS projects. They were distributing their software together, but there was inconsistency across all the projects; each was managed by a different project owner and maintainer. So we focused on the quick start guides for each of these projects to make them consistent.

My mentor wanted me to focus on facilitating these project owners to learn how to do the work, rather than just swooping in, doing the work and leaving. We wanted to enable them to maintain their docs in the future. So we did spend a lot of time on communication. 

Enablement and good communication are two common topics in open source that I feel passionate about. We wanted to continue to work on helping project maintainers create great documentation. So that’s what led to The Good Docs project.

It has a good, diverse group of people attached to it from Australia, the UK, and the US. We released the alpha versions of the templates at the 2019 Write The Docs event in Australia. 

So you’re really all-in with open source now! That is great! How do you find it? Anything surprising?

I find the challenges of group work and getting consensus to be different. When you’re in a business in a hierarchical structure, you know clearly who your stakeholders are. But when you go into an open-source community and it’s all volunteers, you don’t know who to talk to. You want to be respectful because you have an awareness of being part of a larger group. And I’ve come to recognize that help may come from unexpected quarters. 

A friend of mine, who is an open-source developer, said you can’t cut people out who appear to be “onlookers” just watching a conversation take place. You’re never just talking to one person in an open source community context.

How does working with the TYPO3 community compare?

One of the things I have loved while working on the TYPO3 Book is working with the subject matter experts from the TYPO3 community.  

It’s easy to find out who to talk to. I am always checking the TYPO3 Teams pages. It’s clear who to contact and how they want to be contacted. This is immensely helpful. 

I’ve reached out to so many subject matter experts, and cold-called or directly messaged people in the community. And everyone has been so friendly. I fully expected people to be like "I’m too busy" especially considering some were big names In TYPO3. In a business world, you would rarely go straight to the top to ask questions. But I’ve found everyone accessible.

Of course, everyone who has contributed in large or small ways will be appropriately acknowledged in the book, where we will be able to formally express our appreciation. For now, I’d like to give a special thanks to Michael Schams, who also lives here in Melbourne. Since he’s in the same time zone, Michael has ended up bearing the brunt of many of my quick questions about TYPO3. He has been tirelessly helpful, friendly and supportive.

Everyone in the TYPO3 community has been so responsive and helpful. Of course we all have a vested interest in the book being good—it’s good for spreading the word about TYPO3 CMS—which makes me feel very supported.

I have had such positive experiences. The passion that the community has for TYPO3 has not only made it easy for me to work on the book, it has prompted me to get involved and so recently I made my first contribution to the official docs, using the really easy Edit on GitHub process. 

How is the TYPO3 Guidebook coming along?

The book is written in two parts. 

The first part contains four chapters that could give anyone with a technical background insight into how TYPO3 works. It starts with a showcase of what is possible, then a discussion of how you’d think about the design, then how you’d implement it, and what it could take to maintain it. This first part alone would suit decision-makers, consultants, project managers; as well as developers and integrators who are new to TYPO3.

Right now the fourth and final chapter of that part is coming along. We’re moving into graphic design and getting permissions for various assets used in the book. 

The second part contains ten practical guides that start with a problem, discuss solutions, and then guide the reader step-by-step to resolve them. So these are modular chapters, and the reader can dive in and out and refer to them when they need to. 

Cool! Tell us more about the Guides?

These ten chapters cover all the essential and tactical aspects of building TYPO3 projects. Mathias Bolt Lesniak and Benni Mack determined that the topics for the guides should include some for consultants and project managers, and some for developers who are newly adopting TYPO3.

Each guide starts by discussing the why and then moves into the step-by-step how.

  • Creating your first TYPO3 site
  • Extending TYPO3
  • Create your first extension (FormEngine, TCA Fields, plugins, and modules)
  • Plan, build and use content elements
  • Configure content management workflow (including Workspaces)
  • Making TYPO3 successful for your business
  • Configure a multilingual website
  • Site checklist
  • Updating TYPO3 (Major update and bugfix/security update)
  • Debugging and troubleshooting

Writing these guides is going to require technical know-how and user testing so we’ll be consulting with subject matter experts along the way, and of course the entire book will undergo a technical review prior to publishing as well.

How can people keep in touch with the book’s progress?

If anyone would like to follow along, we’ll be sharing more updates on our TYPO3 Book Mailing list.

Sign Up to the TYPO3 Guidebook Mailing List