Tech Writer koduje - odcinek 24 i 25

Dziś kilka słów na temat dwóch ostatnich odcinków podcastu Techwriter koduje.

Odcinek 24

W odcinku dwudziestym czwartym, dobrze Wam już znani prowadzący - Michał i Paweł - dyskutują o API dla dokumentacji, która pozwoli publikować treść tejże dokumentacji w konkretnej apce przy pomocy endpointu. Chodzi o sytuację, w której to aplikacja chce skorzystać z naszej dokumentacji i wyświetlić ją w innym miejscu.

Aby nie teoretyzować, Michał podaje konkretny przykład, w którym wspomniane rozwiązanie było potrzebne. Są wskazane problemy, z jakimi zespół zmagał się przy wdrażaniu dokumentacji “metodami tradycyjnymi” oraz jak wpływały one na użytkownika docelowego. Pomocne okazało się użycie endpointów.

Zdaniem Pawła ma to sens, ale tylko wtedy gdy dane aplikacje są ze sobą połączone i wzajemnie siebie rozumieją, a dokumentacja jest scalana w jednym miejscu, do którego aplikacje mają dostęp i wybierają sobie to, co jest im potrzebne. Ważny jest także fakt, że publikacja aplikacji i dokumentacji następuje w różnym czasie, przez różne zespoły, a ich aktualizacje następują w różnych cyklach. W takiej sytuacji użycie API jest bardzo pomocne i pozwala w łatwy i szybki sposób nadzorować kolejne wersje dostarczanych treści.

Panowie w swej dyskusji rozważają kolejne możliwości użycia API do dokumentacji, problemy jakie z tego mogą wyniknąć, a także co zespoły mogą zyskać dzięki takim rozwiązaniom. Bardzo ciekawy fragment dotyczy scalenia treści dotyczących jednego produktu, który na przełomie dziesięciolecia był wielokrotnie zmieniany i posiada wiele wersji dokumentacji. Jak sprawić by użytkownik miał dostęp do tych wersji w łatwy i czytelny sposób, gdy wiadomo, że dokumentacja i sposób jej udostępniania zmieniał się wraz ze zmianami wynikającymi z rozwoju technologicznego? Jeśli jesteście ciekawi rozwiązania tego problemu, nie pozostaje nic innego, jak włączyć podcast 😉.

Odcinek 25

Tematem przewodnim odcinka jest Markdown - prosty język znaczników, który w ostatnich latach zyskał sporą popularność, szczególnie w świecie dokumentacji dla programistów. Pozwala on łatwo i szybko stworzyć tekst, a następnie opublikować go jako HTML. Z biegiem czasu pojawiły się różne odmiany i rozszerzenia Markdowna, które pozwalają użytkownikom jeszcze lepiej wykorzystać jego możliwości. To właśnie na jednym z nich, czyli MDX, skupiają swą uwagę Paweł i Michał w 25 odcinku podcastu.

Z rozmowy chłopaków dowiemy się czym charakteryzuje się Markdown i do czego można go używać. Dowiemy się także czym jest tajemniczy skrót MDX, skąd wzięło się połączenie Markdowna z JSX (i oczywiście czym ono jest) oraz do czego ta hybryda może nam się przydać. Paweł wspomina o kilku narzędziach, które współpracują z MDX i które mogą przydać się twórcom dokumentacji w codziennej pracy. Najważniejszym punktem rozmowy wydają się być pytania zadane przez Michała:

• co mam jako tech writer z tego, że będę używał MDX?
• dlaczego warto inwestować czas w poznanie tej technologii?
• w jakich sytuacjach MDX może się przydać, a w jakich nie?
• od czego zacząć przygodę z MDX?

Paweł stara się odpowiedzieć na powyższe pytania poprzez przykłady użycia technologii MDX w swojej pracy. Czy przekonał Michała, a także słuchaczy? Musicie to sprawdzić sami odsłuchując podcast.