Tworzenie dokumentacji

Dziś zajmę się dość powszechnym wydaje się problemem, a mianowicie tworzeniem dokumentacji dla oprogramowania. Zwykle owa dokumentacja powstaje dopiero pod koniec tworzenia oprogramowania, nie ma na nią za wiele czasu i oczywiście "chcemy to zrobić tak, by się nie narobić" :). W takim momencie chyba każdemu przychodzi na myśl wykorzystanie jakiegoś edytora (np. Microsoft Word lub OpenOffice Writer). Dlaczego? Bo łatwo i wiele osób wie jak Word'a obsługiwać, jak sformatować tekst, jest automatyczne sprawdzanie pisowni, łatwo dać komuś kto może to sprawdzić pod względem poprawności językowej (nie trzeba być "informatykiem" by obsługiwać Word'a). Gorzej gdy pojawia się konieczność udostępnienia tej dokumentacji w innej postaci. Problemu w zasadzie nie ma jeżeli chcemy przygotować dokumentację w formacie PDF (jest wiele narzędzi, które to umożliwiają, do tego w najnowszego Word'a lub zawsze w OpenOffice Writer'rze jest możliwość eksportu do PDF). Niestety format PDF nie zawsze jest dobrym rozwiązaniem, a dużo popularniejsze są formaty typu "CHM" (Microsoft Compiled HTML Help), strona internetowa, czy dokumentacja zgodna z formatem MSDN'a. Tylko jak coś takiego przygotować?

Help authoring tools

W tym miejscu należy wesprzeć się dodatkowymi narzędziami, które pomogą nam przygotować naszą dokumentację. Narzędzia takie określane są wspólnym mianem "Help authoring" (HAT). Wydaje się, że jest dość ich spora ilość, ale jak się przyjrzeć tym rozwiązaniom bliżej, to albo są one mało wygodne, nie spełniają wymagań, albo kosztowne. W dodatku bardzo często wykorzystują one dziwne formaty plików do zapisywania przygotowanej dokumentacji. Ja ponieważ lubię wybierać darmowe alternatywy (najlepiej z otwartym kodem źródłowym) zwróciłem uwagę na dwa formaty opracowane specjalnie na potrzeby tworzenia dokumentacji elektronicznej.

Pierwszym formatem na który zwróciłem uwagę był DocBook. Jest to otwarty format oparty o XML, w którym można tworzyć dokumentację. Zawiera w sobie definicje specjalnych konstrukcji, które upraszczają późniejsze generowanie dokumentacji. Dodatkowo można znaleźć różnego rodzaju narzędzia, które w automatyczny sposób wygenerują na podstawie plików zgodnych ze składnią DocBook dokumentację w postaci CHM, strony internetowej, czy PDF. Jeżeli ktoś ma ochotę bliżej przyjrzeć się dokumentacji wykonywanej przy użyciu DocBook'a, to zapraszam zajrzeć do pliku pomocy aplikacji TortoiseSVN (pisałem o tym narzędziu w poprzednim post'cie).

Kolejnym formatem, na który warto zwrócić uwagę to MAML, czyli Microsoft Assistance Markup Language.

MAML i przyjaciele

MAML jest językiem opartym o XML i przygotowanym przez Microsoft. Podobnie jak DocBook zawiera w swojej składni elementy umożliwiające przygotowywanie dokumentacji elektronicznej. Są dostępne narzędzia pozwalające wygenerować z MAML'a help'a w postaci CHM, strony internetowej, czy helpa zgodnego z dokumentacją dla Visual Studio i MSDN. Co ciekawe (przede wszystkim dla nas - programistów .NET) można łatwo wygenerować dokumentację kodu źródłowego w tym formacie (wystarczy tylko we właściwościach projektu w Visual Studio zaznaczyć "ptaszkiem" odpowiednie okienko).

Przejdźmy jednak do narzędzi. Najbardziej znanym i liczącym się jest SandCastle oraz jego niemal nieodłączny pomocnik SandCastle Help File Builder (SHBF). To na prawdę ciekawy tandem. Efekty ich działania można zobaczyć (tutaj lub tutaj). Jak łatwo zauważyć dokumentacja przypomina trochę tą znaną z MSDN'a. Można łatwo integrować dokumentację razem z dokumentacją kodu źródłowego. Dzięki wykorzystaniu różnych transformat, np. przygotowanych własnoręcznie transformat można przygotować na prawdę dopasowaną do potrzeb dokumentację.

Przykład fragmentu pliku dokumentacji napisanej w MAML można zobaczyć poniżej:

<?xml version="1.0" encoding="utf-8"?>
<topic id="61c575da-62ae-4651-81df-addc48148450" revisionNumber="1">

  <developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
    <introduction>
      <para>Required introduction</para>
    </introduction>
    <section address="Section1">
      <title>Optional section title</title>
      <content>
        <para>Add one or more sections with content</para>
      </content>
    </section>
    </relatedTopics>
  </developerConceptualDocument>
</topic>

Wracamy do skomplikowanej edycji

W tym momencie chyba jednak trzeba wrócić do problemu z początku: "Jak przenieść przygotowany tekst w jakimś edytorze tekstowym (np. Word czy Writer), do pewnego formatu w jaki przygotowywany będzie system pomocy?". Niestety nie mam jeszcze tutaj gotowej odpowiedzi. Problem polega na tym, że edytory tekstu (w szczególności Word i Writer) ukierunkowane są "na wizualizację tekstu", natomiast formaty, z których można dobrze wygenerować system pomocy ukierunkowane są "na treść".

Spotkałem się z pewnymi próbami, które miały zamieniać tekst z popularnych edytorów na inny format, jednak zawsze nie działało to w sposób optymalny. Do takich przykładów zaliczyć można przygotowane szablony dla DocBooka dla Writer z OpenOffice, czy DocToMaml wchodzący w skład pakietu DocProject. Niestety żadne z tych rozwiązań nie gwarantuje do końca prawidłowej konwersji. Być może coś się zmieni jak powstanie edytor typu WYSIWYG dla MAML (np. taki jak opisywany tutaj, niestety w tej kwestii nie widzę, by się coś zmieniało od niemal roku). Pewne światełko w tunelu oferuje również format Open XML, w postaci którego zapisywane są pliki Word'a 2007, ponieważ jest to format oparty o XML, więc może łatwiej będzie przygotować konwerter. Chyba nawet można łatwo zacząć, korzystając z Open XML Format SDK można w prosty sposób odczytać dokument i jego formatowanie a następnie przeanalizować jego elementy i wygenerować z nich np. plik MAML (tylko kto to zrobi?? jacyś chętni?). Z drugiej strony pozostaje nadal problem z dobrą zmianą "ukierunkowania" dokuemntu: z "na wygląd" na "na tekst".

A może Wy, czytelnicy znacie jakieś inne, dobre (i najlepiej darmowe) rozwiązania wspierające przygotowanie dokumentacji elektronicznej?

Zapraszam do zamieszczania komentarzy.