Jeśli mieliście okazję czytać nasze poprzednie artykuły (jeśli nie, sprawdźcie linki poniżej tego artykułu), możecie już wiedzieć, że w Macopedii często uczestniczymy w programie TYPO3 Community Budget Ideas. Program ten pozwala deweloperom proponować zmiany i ulepszenia w TYPO3, które następnie są poddawane pod głosowanie członków społeczności. Wybrane pomysły są następnie rozwijane w danym kwartale roku. Z powodzeniem dostarczyliśmy ulepszenia w 2024 roku i ponownie w 2025 roku. Jedna z naszych inicjatyw na trzeci kwartał 2025 roku skupiła się na ulepszeniu indeksowania dokumentacji i funkcjonalności wyszukiwania.
Dobra dokumentacja - istotny element oprogramowania
Jednym z kluczowych elementów decydujących o tym, jak dane oprogramowanie jest odbierane, adaptowane i wykorzystywane przez deweloperów, integratorów i edytorów, jest dostarczenie dokumentacji odpowiedniej jakości. Czasami bywa tak, że pomimo tego, że sama dokumentacja jest bardzo obszerna i wartościowa merytorycznie, to odnalezienie w jej zasobach interesujących nas informacji bywa kłopotliwe. Może to wynikać z wielu przyczyn, ale często bywa tak, że same wyszukiwarki umożliwiające filtrowanie i przeszukiwanie zasobów dokumentacji nie działają do końca poprawnie.
Korzystając często w naszej pracy z dokumentacji TYPO3, zauważyliśmy, że są obszary, które mogą być w niej usprawnione - szczególnie te związane z tym, jak indeksowane są treści i jak generowane oraz prezentowane są wyniki ich wyszukiwania. Nasze pomysły dotyczące potencjalnych usprawnień w dokumentacji TYPO3 zgłosiliśmy w trzecim kwartale tego roku jako jedną z inicjatyw programu Community Budget Ideas. Zostały one pozytywnie odebrane przez społeczność i w wyniku głosowania, zaakceptowane do realizacji.
Plan prac krok po kroku
Zgłaszając naszą inicjatywę dotyczącą wprowadzenia usprawnień w wyszukiwarce dokumentacji TYPO3, przygotowaliśmy dosyć szczegółowy plan realizacji prac, które planowaliśmy wykonać. Dużą część tego planu stanowiły analizy i konsultacje, których celem było wypracowanie i określenie konkretnych zmian, jakie miały być wprowadzone od strony deweloperskiej. Plan ten przedstawiał się następująco:
- Konsultacje z zespołem odpowiedzialnym za dokumentację TYPO3 w celu uzgodnienia, jak wyszukiwarka dokumentacji powinna wyglądać oraz jakie funkcjonalności i możliwości powinna oferować
- Konsultacje z ekspertem od Elasticsearcha w celu omówienia optymalnej struktury indeksu danych
- Przygotowanie we współpracy z ekspertem od Elasticsearcha odpowiedniej struktury indeksu danych, aby pozwalała ona na szybkie i precyzyjne przeszukiwanie dokumentacji w celu zwrócenia wyników jak najbardziej odpowiadających temu, czego użytkownik szukał
- Zmiany w aplikacji indeksującej dane oraz przygotowanie endpointów API, które będą współdziałały z nową strukturą indeksu danych, w celu generowania podpowiedzi dla wyszukiwanych treści oraz zwracania precyzyjnych wyników wyszukiwania
Burza mózgów i mockupy nowej wyszukiwarki dokumentacji
Nasze prace rozpoczęliśmy od zaplanowania spotkania, w którym uczestniczyli Marcin Sągol oraz liderka zespołu odpowiedzialnego za dokumentację TYPO3, Lina Wolf. Podczas spotkania Lina przedstawiła swój punkt widzenia na zmiany dotyczące obsługi wyszukiwania w dokumentacji oraz wizję kierunku, w jakim powinien ewoluować interfejs wyszukiwarki. Zależało jej, aby narzędzie oferowało bardziej zaawansowane możliwości filtrowania i zawężania wyników wyszukiwania, zbliżając się funkcjonalnością do tego, co oferują wyszukiwarki na platformach takich jak GitHub czy Slack.
Aby upewnić się, że zarówno nasz zespół deweloperski, jak i zespół zarządzający dokumentacją TYPO3 w pełni rozumieją kierunek, w którym chcemy podążać, podczas pierwszego spotkania przygotowano również mockupy wyszukiwarki (w Figmie). Przedstawiały one funkcje i zachowanie narzędzia w różnych scenariuszach jego użytkowania.
The new search system is designed to offer an advanced suggestion mechanism, including links to documentation pages and the ability to narrow the search scope to a specific manual (e.g., documentation for a particular extension), vendor, option, or version.
| Search scope | Description |
| global | Allows to search in all manuals (vendor/package), options and versions - any restrictions/scopes are ignored |
| manual | Allows to search only documentation which belongs to the given manual (vendor/package). Examples: georgringer/news, typo3/cms-core (so the scope is given composer package) |
| vendor | Allows to search only documentation files which belong to the given vendor. If there are multiple manuals which belong to the same vendor, they all will be searched. Example: georgringer, typo3 |
| option | This will be a new feature. Some files will contain documentation for the so-called Option. An Option will be a special group which documents related configuration like for TCA. The documentation files in the tags containing sections can contain data-search-facet attribute, which points to a section.; |
| version | This will narrow the search scope only to the given manual version |
Optimizing the ElasticSearchindex structure
To ensure the new TYPO3 documentation search engine is both fast and effective in delivering accurate, filtered results, we sought advice from an ElasticSearch expert.
We consulted Rafał Kuć, a renowned specialist and author of several ElasticSearch books. We presented our objectives to Rafał and sought his guidance on designing an optimal data index structure. The goal was to organize the data to enable filtering by documentation type, extension, version, and other criteria while maintaining high performance. A few days later, we received a set of recommendations from Rafał, which allowed us to proceed to the final implementation stage.
Development work: ElasticSearch index updates and API adjustments
TYPO3 documentation relies on manuals provided by TYPO3 team members or extension authors, generated as HTML files from reStructuredText (RST). These files undergo an indexing process managed by a Symfony-based application. During indexing, each HTML file is split into sections, enabling more precise search results by linking users directly to specific documentation fragments rather than entire pages.
The changes made to the indexing application and ElasticSearch index structure, primarily developed by Oskar Dydo, enabled the creation of an advanced search suggestion mechanism and improved search scope management. The new API allows for dynamic narrowing of search results as the user types, though multi-phrase queries are not yet supported.
All the changes were implemented in the t3docs-search-indexer repository. Additionally, we created documentation detailing the updated ElasticSearch index structure and the new API endpoints. This document provides information on query parameters, the data structure returned by the API, and a detailed explanation of the suggestion mechanism.
Summary of the TYPO3 documentation search Initiative
The primary focus of this initiative was on backend improvements. The work included extending the ElasticSearch index structure, modifying the data indexing process, and adding new API endpoints to support scenarios like narrowing search scopes or providing suggestions based on package names, vendors, versions, or options.
We hope that a new search frontend will soon be developed to fully utilize these functionalities, ultimately enhancing the user experience for those navigating TYPO3 documentation. :)
Related links:
https://macopedia.com/blog/news/typo3-documentation-search-improvements
https://macopedia.com/blog/news/access-control-lists-in-typo3-research-and-planning-improvements