W zeszłym tygodniu ciężkim czwartku i piątku chciałem popełnić długaśny post na temat ogólnie dokumentacji projektu, ale tak jak ledwo, co byłem wstanie wysiedzieć w pracy w te dwa ostatnie dni tak też przy pisaniu poniosły mnie można by powiedzieć emocje. Skończyło się tym, że po 4 stronach A4 zamknąłem Worda nie zapisując dokumentu i nie chcą nigdy więcej do tego wracać. Może jak mi przejdzie to usiądę i napiszę to chciałem ujmując to w bardziej przyjemne słowa.

Jednakże chcę i to teraz poruszyć jeden z aspektów, które opisywałem wyżej wymienionym dokumencie. Od dawien dawna jak tworzyłem (lub firma, w której pracowałem tworzyła) dokumentację do bazy danych, wykorzystywaliśmy program, który w stanie Texas został zakazany. Cała praca nasza polegała na stworzeniu tabelki, która zawierała takie informacje jak:

  • Nazwa kolumny;
  • Typ danych;
  • Czy może być NULL;
  • Opis.

Do tego dochodził opis tabeli, view, procedur wbudowanych i innych rzeczy, które dało się opisać.

Patrząc na swoją przeszłość teraz stwierdzam, że nie było tak źle. Dokumentacja zazwyczaj powstała na końcu projektu, a po maratonach nocnych była to naprawdę miła odmiana i mały odpoczynek. Jednakże tak być nie powinno.

U siebie w pracy dostałem zadanie sprawdzenia i aktualizacji aktualnej dokumentacji, i wszystko było by piękne gdyby nie dokumentacja schematu bazy danych. Mianowicie ostatni raz była ona aktualizowana 2 miesiące temu. W tym czasie było ponad 150 checkinów skryptów ją tworzących. Stanąłem przed dylematem. Pisania dokumentacji od nowa lub porównywania każdego opisu i każdej wartości po kolei. Nie wiem jak wy byście zareagowali, ale mnie na samą myśl, że mam robić za WinDiff szlak trafił.

Zacząłem więc szukać alternatywnych dróg dokumentowania bazy danych z nadzieją, że jednak coś się znajdzie. No i się znalazło! I to masę a wszystkie opierające się na tym samym prostym mechanizmie:

Dodania rozszerzonej własności (extended property) do schematu bazy danych. Ta własność to MS_Description, która przechowuje opis danego elementu czy to tabeli, czy kolumny.

Zarządzanie odbywa się za pomocą procedur wbudowanych:

Teraz by na przykład dodać opis tabeli i procedury wbudowanej wystarczy wykonać polecenie:

EXEC sp_addextendedproperty N'MS_Description', N'Tabela przechowuje informacje o wiadomościach tekstowych wysłanych z systemu (API oraz GUI).', 'SCHEMA', N'dbo', 'TABLE', N'MessageOut', NULL, NULL

GO

EXEC sp_addextendedproperty N'MS_Description', N'Test opis procedury', 'SCHEMA', N'dbo', 'PROCEDURE', N'spEndContactGroupsAssignment', NULL, NULL

GO

EXEC sp_addextendedproperty N'MS_Description', N'opis parametru 2', 'SCHEMA', N'dbo', 'PROCEDURE', N'spEndContactGroupsAssignment', 'PARAMETER', N'@confirm'

GO

Proste prawda? Oczywiście stworzenie takiego skryptu dla N tabel i X kolumn nie jest przyjemne, ale o tym później.

Ogólnie schemat polecenia możecie znaleźć w linkach wyżej podanych, nie będę się tutaj nad tym rozwodził.

Jednakże, co to nam daje? A daje nam ogromnie dużo, teraz za pomocą aplikacji trzeciej lub własnego kodu, możemy w prosty sposób wygenerować, tak, wygenerować dokumentację dla bazy danych.

Kilka płatnych aplikacji, które wspierają taki sposób dokumentowania baz danych:

  • RedGate SQL Doc – bardzo przyjemna i prosta w obsłudze aplikacja, która może nam wygenerować dokument Word jak i CHM. Także umożliwia wprowadzanie opisów bezpośrednio z narzędzia. Minusem IMO jest czcionka wygenerowana w CHM, wolałbym, aby to było raczej w stylu MSDN, albo żebym miał wybór jakiś. Tak to narząd ko jest na tyle inteligentne, że jak nie ma opisu czegoś to nie wstawi pustego pola Description, tylko je usunie;
  • DBScribe – Wizardowa aplikacja, która krok po kroku prowadzi nas prosząc o podanie i wybranie kilkunastu opcji. Na szczęście można zapisywać profile, bo na jedne stronie wizarda, mamy około 100 checkboxów do zaznaczenia. Ale, dzięki czemu możemy dokładnie określić co chcemy by było pobrane i udokumentowane. Niestety nie umożliwia ona w żaden sposób (przynajmniej wersja darmowa) dokumentowania bazy, jedynie generuje w miarę przyjemnie wyglądający plik CHM (nie jest on na tyle przyjemny co SQL Doc, i kolorystyka tabelek użyta jest na tyle wyraźna, że może niektórych z niechęcić, ale nie jest zła) i tyle;
  • DBDesc – Trzy zakładkowa aplikacja, prosta w obsłudze, bez większych fajerwerków. Jednakże podobnie jak SQL Doc udostępnia edytor rozszerzonych własności – plus i to duży dla aplikacji. Wynik jednak wygenerowanego dokumentu, pozostawia wiele do życzenia, naprawdę odradzam;
  • Documenter – wygląd interfejsu a la Office 2007, przyjemny w użyciu i na tym się kończy zabawa. Za dużo opcji do ustawiania nie ma, także nie ma możliwości tworzenia dokumentacji z narzędzia. Jedynie generowanie. Za to wynik jest naprawdę śliczny, lepszy od DBScribe ale przegrywa z SQL Doc w jednej rzeczy – rozszerzone własności są wyświetlane osobo w tabeli Rozszerzone Własności oraz brak zaciągania opisów kolumn – choć to akurat może być winą wersji trial;
  • Document! X – najbardziej zaawansowany produkt na jaki trafiłem można w nim zrobić prawie wszystko a wygląda jak dokumentacja MSDN. Umożliwia edycję własności, podgląd i zmianę wielu elementów wyglądu dla generowanego dokumentu. Ma tyle opcji, że szczerze nie miałem ochoty się im przypatrywać. Ale daje nie tylko możliwość dokumentowania bazy danych, także kodu co tworzy go centrum generacji dokumentacji projektowej.

Czy są to wszystkie aplikacji dostępne na rynku? Na pewno nie! Jest ich paręnaście, niektóre darmowe, niektóre płatne. Niektóre generują obrzydliwe pliki, inne zaś ładne.

Ja osobiście przetestowałem te powyższe i wybrałem SQL Doc, jest prosty, przyjemny i można szybko wygenerować dokumentację. Dodatkowym atutem jest także generowanie przez niego skryptów tworzących opisy, przez co można je potem wykorzystać jak będzie taka potrzeba.

To czego mi brakuje we wszystkich tych programach to generowania diagramów, choć wydaje mi się iż firma ValeSoftware ma takie rozwiązanie, które to umożliwi – niestety jak tylko próbuje otworzyć stronę to mi coś siada i nie jestem wstanie w pracy jej obejrzeć. Może sprawdzę tę aplikację w domu?

A wy jakiego używacie programu? Używacie jakiegoś? Może macie inny sposób generowania dokumentacji. Dajcie znać w komentarzach! :)

PS: Jeżeli interesują was przykłady z powyżej wymienionych aplikacji, dajcie znać.

PODOBNE ARTYKUŁYWIĘCEJ OD AUTORA