Usprawnienia w wyszukiwarce dokumentacji TYPO3

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.