Elastyczna dokumentacja z DITA

Standardowe oprogramowanie jest dostarczane ze standardową dokumentacją. Oprogramowanie jest często dostosowywane do konkretnych potrzeb klienta. Powoduje to konieczność rozszerzenia standardowej dokumentacji o funkcje specyficzne dla klienta. Dokumentacja projektudokumentacji jest tworzona na podstawie standardowej.

W jaki sposób zapewnić, że dokumentacja standardowa i dokumentacja projektu będą nadal działać synchronicznie, nawet w przypadku aktualizacji i dalszego rozwoju standardowych funkcji, i że nie trzeba będzie utrzymywać dwóch statusów dokumentacji równolegle?

Przemyślenia: Dokumentacja jako "kod źródłowy", który jest rozwijany w sposób zwinny, podobnie jak oprogramowanie.

Rozważmy standardowe oprogramowanie, w tym dokumentację, jako samodzielny projekt rozwojowy.

Wtedy źródła i pliki naszej dokumentacji są kodem źródłowym, analogicznym do kodu źródłowego naszego oprogramowania. W tym ujęciu nasza dokumentacja jest jak oprogramowanie.

Składa się z modułów dokumentacji podstawowych zasobów wielokrotnego użytku. Dokumentacja jest tworzona jak oprogramowanie. W idealnym przypadku robimy to równolegle z cyklem rozwoju oprogramowania.

Zmiana tego sposobu myślenia oznacza zmianę sposobu pisania, a raczej tworzenia dokumentacji.

W scenariuszu, który tutaj przedstawiamy, tworzenie dokumentacji musi być dostosowane do procesów tworzenia oprogramowania lub przynajmniej do nich zbliżone.

Aby tworzenie dokumentacji mogło być w znaczący sposób zintegrowane z rozwojem oprogramowania, narzędzia do tworzenia dokumentacji nie mogą opierać się na zastrzeżonych formatach danych (takich jak nieustrukturyzowany FrameMaker, InDesign, Word).

Formaty te są nieodpowiednie, ponieważ nie nadają się do odczytu maszynowego przez cały czas bez skomplikowanych konwerterów. W naszym scenariuszu jest to jednak dokładnie to, czego potrzebujemy.

To prowadzi nas do XML, a tym samym do obecnie uznanego standardu DITA. Tworzenie dokumentacji w oparciu o DITA może wykonywać opisane powyżej zadanie "rozwijania" standardowej dokumentacji i dokumentacji specyficznej dla projektu równolegle z procesem tworzenia oprogramowania.

Zwinny sposób myślenia i środowisko narzędzi, które opiera się na ustalonych standardach, stanowią dobrą podstawę do połączenia zespołów technicznych i programistycznych. deweloperzy są włączone w proces tworzenia dokumentacji jako dostawcy treści. Więcej: Zewnętrzni projektanci, deweloperzy i konsultanci również mogą zostać włączeni w proces tworzenia dokumentacji. Możemy dostarczyć im treści do dokumentacji specyficznej dla projektu w oparciu o modułową podstawę wielokrotnego użytku.

Przyjrzyjmy się koncepcjom, za pomocą których DITA może wspierać nas w zwinnej dokumentacji.

Badamy tę kwestię: Jak możemy wykorzystać w pracy redakcyjnej narzędzia, które są już znane z tworzenia oprogramowania?

Wykorzystanie mechanizmów ponownego użycia w DITA do elastycznego tworzenia dokumentacji

Ponowne użycie jest jedną z podstawowych koncepcji DITA. I to właśnie te bardzo dojrzałe i wyrafinowane koncepcje pomagają nam we wdrażaniu dokumentacji oprogramowania specyficznej dla projektu.

Mechanizm conref jest również łatwy do zrozumienia.

Treści z puli zasobów mogą być przywoływane i integrowane z publikacją.

Na przykład Adobe FrameMaker implementuje podobny mechanizm w wariancie nieustrukturyzowanym, wykorzystując wstawki tekstowe.

Wstawka tekstowa to fragment, który jest przechowywany jako samodzielny plik, a następnie włączany do treści jako kopia z odniesieniami.

Zmiana tego fragmentu powoduje zmianę całej zawartości, do której ten fragment się odwołuje lub w której jest osadzony.

DITA idzie tutaj o krok dalej: Adresowanie za pomocą identyfikatorów w temacie zasobu można również wykorzystać do uwzględnienia tylko określonej części, zaczynając od zdefiniowanego identyfikatora i kończąc na innym identyfikatorze.

Pojedynczy temat może zatem zawierać kilka zasobów, które są zintegrowane w różnych miejscach.

Praktycznym tego przykładem jest centralna definicja instrukcji bezpieczeństwa i ich integracja w odpowiednich punktach dokumentu/kontekstu tematycznego.

<keydef keys="project.screenshots" href="screenshots.dita" format="dita"/>

<keydef keys="project.screenshots" href="screenshots-project-A.dita" format="dita"/>

Poniższe sekcje przedstawiają dwa przypadki użycia mechanizmów Reuse. Są to teksty interfejsu i zrzuty ekranu, a także zarządzanie wariantami za pomocą profilowania.

Następnie przyjrzymy się zaletom i możliwościom, które wynikają ze zmienionego i, jak widzimy, "nowoczesnego" sposobu patrzenia na tworzenie dokumentacji równolegle z tworzeniem oprogramowania.

Dotyczy to zarządzania treścią dokumentacji, planowania publikacji i integracji podmiotów zewnętrznych z procesem dokumentacji.

Pierwszy przypadek użycia: Teksty interfejsu i zrzuty ekranu

Dokumentacja oprogramowania często wykorzystuje teksty, które pojawiają się w interfejsach oprogramowania, aby ustanowić odpowiednią relację między dokumentacją a oprogramowaniem.

Radzenie sobie z tymi tekstami nie zawsze jest łatwe, zwłaszcza jeśli dokumentacja ma zostać przetłumaczona na kilka języków.

Aby prawidłowo skonfigurować ten proces, wymagany jest interfejs między rozwojem a edycją techniczną.

Jeśli oprogramowanie jest najnowocześniejsze, teksty interfejsu są przechowywane w zewnętrznych plikach zasobów, tłumaczone i integrowane z oprogramowaniem w zależności od języka.

Dlatego sensowne jest generowanie Key-Maps z tych plików zasobów w procesie kompilacji oprogramowania. Odpowiednie treści w dokumentacji mogą być następnie przywoływane z tych kluczowych map. Dzięki temu dokumentacja jest zawsze aktualna i poprawna.

Niektóre kompilacje oprogramowania posuwają się nawet do automatycznego generowania zrzutów ekranu, które częściowo zależą od języka, a także od projektu.

Możemy również użyć tego mechanizmu podczas tworzenia dokumentacji, aby utworzyć tematy specyficzne dla języka i projektu, które odwołują się do tych zrzutów ekranu (patrz przykład kodu źródłowego powyżej). Korzystając z conkeyref, możemy automatycznie dołączać zrzuty ekranu do dokumentacji różnych projektów.

Drugi przypadek użycia: Zarządzanie wariantami

DITA zapewnia Profiling w celu wykluczenia określonych treści z danych wyjściowych.

Powoduje to wygenerowanie dokumentacji specyficznej dla klienta. Dzieje się to za pośrednictwem atrybutów. Mechanizmy profilowania są kontrolowane podczas publikacji za pomocą tak zwanego DITA-VAL.

Profilowanie znaczników jest możliwe w prawie wszystkich DITA. W razie potrzeby można je również rozszerzyć poprzez specjalizację, aby zaspokoić określone potrzeby.

Jeśli spojrzeć na tę funkcję w oderwaniu od innych, już teraz pomaga ona w generowaniu dokumentacji specyficznej dla projektu.

W połączeniu z opisanymi mechanizmami ponownego użycia, możliwości jeszcze bardziej rosną. Wynika to z faktu, że tematy ponownego użycia lub kluczowe mapy mogą być również odpowiednio uwzględniane lub wykluczane za pomocą mechanizmu profilowania. Osiągnięto maksymalny stopień elastyczności.

Integracja dokumentacji z procesem tworzenia oprogramowania: Zarządzanie treścią

W wielu projektach programistycznych stosowane są systemy kontroli wersji (VCS), takie jak GIT, Bitbucket lub (bardziej klasycznie) SVN.

VCS oferuje zatem elastyczną, zorientowaną na wydania opcję zarządzania kodem źródłowym.

Zgodnie z naszym nowym poglądem, dokumentacja techniczna to po prostu kod źródłowy.

Dlatego właśnie potrzebujemy zarządzania kodem źródłowym. I to taki, który jest zorientowany na cykle wydawnicze naszego oprogramowania. Administracja, która pozwala nam również zintegrować naszą dokumentację z różnymi statusami rozwoju oprogramowania.

Jeśli będziemy postępować w ten sposób, zrównamy nasze wydania dokumentacji z oprogramowaniem, po prostu zarządzając nimi na odpowiednich etapach rozwoju.

Jest to szczególnie pomocne w przypadku naszej dokumentacji projektowej, ponieważ adaptacje specyficzne dla klienta są naturalnie opóźnione w stosunku do najnowszej wersji podstawowej oprogramowania. Dokumentacja projektu musi zatem być w stanie wykorzystywać podstawowe zasoby ze starszych wersji oprogramowania.

Jest to możliwe dzięki wykorzystaniu VCS i przypisaniu określonych statusów dokumentacji do określonych wersji oprogramowania.

Planowanie publikacji dokumentacji: codzienne/nocne kompilacje

Ponieważ postrzegamy dokumentację jako kod źródłowy, możemy również spojrzeć na proces publikacji jak na proces tworzenia oprogramowania. W wielu scenariuszach kompilacje oprogramowania uruchamiane są automatycznie. Uwzględniają one testy i walidacje, zwłaszcza w Test-Driven Development.

DITA Open Toolkit to darmowe narzędzie dostępne jako open source.

Pozwala nam to automatycznie zintegrować generowanie różnych wariantów dokumentacji, w tym wyników specyficznych dla projektu, z procesem tworzenia oprogramowania. Możemy zatem dodać generowanie dokumentu do kroku roboczego, który dostarcza nam zaktualizowane teksty oprogramowania i zrzuty ekranu.

W ten sposób mamy dostępną dokumentację, która jest aktualna i odpowiednia do statusu oprogramowania, powiązana z różnymi wersjami, a nawet, jeśli to konieczne, dla różnych pośrednich statusów oprogramowania i powiązanej dokumentacji.

Proces tworzenia dokumentacji może weryfikować zawartość na etapach pośrednich. Można to zrobić zarówno strukturalnie, jak i w odniesieniu do zmiennych referencyjnych i innych komponentów Reuse.

Rezultatem jest raport o wszelkich błędach lub problemach znalezionych w bazie danych, który w razie potrzeby może być przerabiany codziennie (przed kolejnym wydaniem).

Zaangażowanie podmiotów zewnętrznych w tworzenie dokumentacji

Po stworzeniu i udostępnieniu podstawowych zasobów dostarczamy je stronom trzecim, na przykład konsultanci lub projektanci. W idealnym przypadku dostarczamy tę dostawę wraz z szablonami tworzenia. Na podstawie szablonów podmioty zewnętrzne mają możliwość tworzenia dokumentacji projektowej, z zastrzeżeniem, że podstawowe zasoby nie są zmieniane.

W najprostszym przypadku dostosowują zmienne specyficzne dla projektu (keyref) w plikach szablonów i dodają szczegóły specyficzne dla projektu w dodatku, które początkowo nie mają nic wspólnego z samym oprogramowaniem.

Podczas dostosowywania oprogramowania, tj. podczas konfiguracji lub, w razie potrzeby, poprzez własne rozszerzenia programistyczne, zawartość jest teraz uzupełniana lub zastępowana za pomocą rozszerzonych mechanizmów ponownego użycia.

Wnioski: Dokumentacja, która pasuje

Ponieważ oprogramowanie jest już samo w sobie ustrukturyzowane, w konkretnych przypadkach można również znaleźć sposoby na wyodrębnienie informacji bezpośrednio z oprogramowania i zintegrowanie ich z dokumentacją.

Najprostszym przykładem są tutaj teksty interfejsu oprogramowania.

Podejście to jest wprawdzie złożone i wymaga odpowiedniej krzywej uczenia się, zwłaszcza gdy w grę wchodzą strony trzecie.

Zalety tego podejścia są jednak oczywiste: Jeden wykorzystuje istniejącą standardową dokumentację i dostarcza dokumentację dostosowaną do potrzeb klienta.

Jest to możliwe poprzez zmianę lub zastąpienie dokładnie tych treści, które odbiegają od wymagań klienta. Przy następnej aktualizacji oprogramowania relacje (np. conref) są nadal obecne.

Dokumentacja aktualizuje się w standardowym obszarze. Co więcej, nie jest konieczne odtwarzanie całej dokumentacji, a jedynie części, które faktycznie zmieniły się z jednej wersji na drugą.

A co z firmami, które nie akceptują danych xml jako dostawy, ale oczekują Word?

Ta grupa docelowa również może otrzymać wsparcie. Word programu Word to tylko kolejna forma dostarczania treści. Można go łatwo wygenerować z istniejących zasobów dokumentacji DITA.

Opisana tutaj infrastruktura stanowi rozwiązanie dokumentacyjne oparte na ustalonych standardach i w większości już istniejących procesach i narzędziach. Rozwiązanie to jest zintegrowane z procesem tworzenia oprogramowania. Czy jest coś złego w umożliwieniu klienci, konsultanci, deweloperzy i projektanci dostępu do tej infrastruktury jako specjalnej usługi i zintegrowaniu jej z procesem, a tym samym związaniu ich z firmą?

To, co opisano tutaj w odniesieniu do dokumentacji oprogramowania, można łatwo przenieść na instrukcje obsługi, oferty, umowy i inne rodzaje dokumentacji.

Nasza oferta: Konwersja FrameMaker Word, InDesign, do formatu DITA

Wspieramy Cię na drodze do dokumentacji opartej na standardach, a tym samym otwierającej wiele możliwości automatyzacji.