Start Improving Docs Now to Grow TYPO3

Everyone using TYPO3 benefits from documentation, and everyone has skills they can use to improve it. It’s probably easier than you think. Docs contributors help fix typos, add code samples, and update screenshots in the documentation. Thank you for that! Now we need more help. Here’s why and how you can start contributing right now in a few quick steps.

Each month, we report on contribution in the Developer Appreciation Day (DAD) posts. (Thank you all, you’re amazing!) On average there’s a ratio of 4:1 code contributors to documentation authors, and we’d like to improve that. The TYPO3 Documentation team is doing a great job coordinating this activity, but they need your help.

Software projects need documentation, but open source needs it more so. Without documentation, no one will know how to use it or contribute to it. It’s that simple. Both new and experienced users rely on references that explain how TYPO3 works. Contributors need guides showing them the TYPO3 contribution workflow.

Documentation is also the likely place where newcomers will get stuck. “Outdated” content was found to be a demotivating factor for newcomers. They could be wasting time and getting frustrated. Newcomers are also likely able to make the biggest impact with their fresh perspective.

We can’t rely on someone to take care of documentation for us. It’s every user’s responsibility to make the documentation awesome. And I do think TYPO3 documentation is awesome and getting better. The Documentation Team is a mere four people right now, and they do a tremendous job coordinating the help of contributors who fix typos, add new chapters, and update code samples.

They don’t need to grow the team, but they want to see more people pitch in to help out. As you’re using TYPO3, keep note of things you find confusing. If you’re stuck and you do find errors, don’t assume someone else knows. Report it. And after this, we hope you’ll jump in and fix it!

We need to improve documentation to make TYPO3 easier to use. And, dear reader, that’s where you come in. “Me?” you say - Yeah, you!

Documentation is something everyone, and every user can contribute to, no matter your skills and ability. Write the Docs, a community built around raising awareness of the importance of documentation, says:

“If you care about documentation and communication in the software industry, you’re a documentarian.”

They list the obvious contributors such as programmers and technical writers who benefit from clear and thorough documentation every day. But they also point out salespeople, support people, and users themselves make use of documentation. They can make important contributions, too.

You too can be a documentarian! We need you to step up and get involved, and it’s a lot easier than you think.

From a technical perspective, GitHub has made contribution easier for us. Researchers found the move to GitHub could attract new contributors to open source projects, however an increase in actual contributions wasn’t guaranteed. Newcomers need clear guidelines and pathways to contribution, and that is what the TYPO3 Documentation Team has been working on.

The switch to GitHub has definitely made a big impact on TYPO3 documentation. Martin Bless, TYPO3 Documentation Team Lead said “Before 2017, the documentation team was responsible for writing the actual text. Now the documentation team itself doesn’t write all the text. That may sound like bad news, but it’s great news. So many others have taken over.”

Having better tools mean the docs team is in the role of facilitating contribution, and it’s much easier to get involved now. It’s gone from a handful of contributors to hundreds of contributors over time with an average of 17 per month. Martin said, “In the olden days there were only one or two people who could edit the documents. They actually had to write everything. Today, if you look into the documentation repositories today, many people are making many contributions.”

Lots of users are already familiar with GitHub, and for those who are completely new, there’s a great UI if you want to make changes directly in the browser. It’s as simple as clicking “Edit me on GitHub.”

You can use this GitHub method demonstrated in the video for small changes. You don’t have to worry about being perfect. Sybille Peters from the Documentation Team says, “My personal advice from my experience: Just start. You don't have to worry too much about doing stuff wrong. You will learn as you go along. Any change you create with GitHub pull requests will not be visible immediately, it needs to be merged by experienced maintainers. They will give you feedback. Don't worry. Just don't start with a huge change. Start small.”

If you have bigger ideas, read on for more tips on getting involved. This video explains the GitHub method, where you can edit right in the browser.

The spirit of open source is developers and users “scratching their own itch.” Sybille says to start there. Look at the tutorials and guides you may have used already. “What hurts you most? What bothers you? Where do you see a need for improvement? Get started on that. Don't just write issues. Make the changes you find useful yourself, as a pull request.” It’s an open invitation to jump right in.

How is it organized?

Documentation is hosted on GitHub in its own TYPO3 Documentation project. Various documentation manuals each have their own repository with the source code for editing and collaboration. Then, the manuals get published on docs.typo3.org. For example, the TYPO3CMS-Guide-Installation repository is on GitHub and that is published as the TYPO3 Installation Guide here. See more about how documentation is organized.

How to contribute?

Follow the guide on Writing Documentation for TYPO3 and Documentation contribution guide. Consult the TYPO3 writing style guide too for general terms and spelling. Native English speakers can help out even with copy editing.

Where to start?

There are many kinds of contributions you can make to documentation. Even small fixes are much appreciated. Maybe you saw an error as you followed instructions. Maybe you saw an out of date screenshot.

And YES, pedantic typos or grammar corrections are very welcome too.

• If you have an idea or see a problem, and it’s a straightforward correction, you can use the GitHub method shown in the video above. Making an issue for small fixes isn’t mandatory.

• If you have a more complicated suggestion or new content idea, ideally you’d start by creating an issue before making changes. Someone else might be working on something similar, or they might have suggestions on the best way to approach it.

• If you’re not even sure where to make the issue, don’t hesitate to join the docs Slack channel to ask: #typo3-documentation. Here’s all you need to know about Slack in the TYPO3 community.

• If you don’t have ideas but want to help, start by browsing a manual you use often or what best fits your expertise, and peruse the open issues there. In every official manual you should find a link to the issues by clicking on Related links in the navigation menu. Here’s how to help

Don’t let even language barriers stop you. Sybille says “The English language is a REAL problem for some people. I've heard this more than once. They feel their English language skills are not good enough.” She suggests a solution, “Find someone on Slack to collaborate with. Some people are happy to just edit text.”

What’s going on right now?

To see what has been going on recently, you can visit Documentation Team News for updates. Also, hop into #typo3-documentation in Slack. Here’s how to register for TYPO3 Slack.

It’s easier than you think to make even a small contribution. Areas like documentation are often overlooked in open source, so non-technical contributors are very welcome. Newcomers, especially with their fresh perspective and questions, can make a big impact on documentation.

As you saw in the video above, editing documentation is getting easier. There are lots of resources already showing you how to get involved, but the best thing is to talk to directly to the people involved. Slack is the best way; #typo3-documentation. Not in Slack yet? Register for TYPO3 Slack.

See you there!