fbpx

Jak dokumentować system raportowy

Celem dokumentowania danych jest pomoc użytkownikom w ich znalezieniu, zrozumieniu i pewności korzystania z nich. 

Ale nie musisz wszystkiego dokumentować. Dobrze wymodelowane dane są często oczywiste. 

„Dobry kod sam w sobie” zawiera sporo prawdy. Powinieneś dążyć do posiadania wyrazistych i spójnych nazw, które są samo opisowe. Czyli sama nazwa niesie informację. Baza danych o nazwie „dbo” nie jest pomocna, „sales_prod” jest lepsza, zwłaszcza jeśli istnieje również baza danych „sales_dev” i „finance_prod„. 

Tak więc dokumentowanie zaczyna się od nazywania rzeczy, ale na tym się nie kończy. 

Użyj hierarchii systemu bazy danych, aby zbudować dokumentację odgórną: 

POZIOMNAZWA MINIMALNY OPIS PRZYKŁAD 
1 System Przeznaczenie systemu Opis wprowadzający Kontakt do osoby odpowiedzialnej [Postgres] Postgres to główna baza analityczna dla sprzedaży i logistyki. Opiekunem bazy jest Marcin Karwowski, [email protected] 
2 Baza danych Przeznaczenie i zawartość bazy danych Zespół i osoby odpowiedzialne Logi_prod – to jest produkcyjna baza danych obszar logistyka. Zawiera surowe oraz przeliczone dane z WMS oraz ERP. Właściciel Marcin Karwowski, [email protected] 
3 Schemat Przeznaczenie i zawartość schematu Zespół i osoby odpowiedzialne WMS – schemat zawierający tabele z WMS. Właściciel Marcin Karwowski, [email protected] 
4 Tabela Przeznaczenie i zawartość tabeli Zespół i osoby odpowiedzialne Linie_zamowien – każda linia to podejście do półki operatora systemu WMS Właściciel Marcin Karwowski, [email protected] 
5 Kolumna Zawartość kolumny DataUtworzenia – data, kiedy linia została utworzona, jest to skan półki 
Przykładowy opis danych w systemie raportowym

Dzięki temu użytkownicy zaczną rozumieć ogólny schemat i będą mogli samodzielnie poruszać się po oceanie danych. 

Na czym należy się skupić podczas dokumentowania danych 

Całkowicie udokumentuj 3 najwyższe poziomy (system, baza danych, schemat). Skoncentruj się na udokumentowaniu 10% najczęściej używanych tabel. Ustal proces, w którym wszystkie nowe tabele/widoki/modele powinny być tworzone przy co najmniej minimalnej dokumentacji (podczas tworzenia jest to najłatwiejsze do udokumentowania). 

Dokumentowanie wszystkich kolumn jest zwykle warte tylko w przypadku produktów danych lub powszechnie używanych tabel raportowania. Ale w tym przypadku powinieneś być rygorystyczny. Jeśli kolumna nie jest warta udokumentowania, nie powinna być częścią tabeli. 

W praktyce dobór odpowiednich słów może być trudny. Czy powinienem odnosić się do klienta lub konta, firmy, użytkownika lub witryny?  Czy wszyscy rozumieją akronimy, których używamy w naszym zespole? 

Aby sprostać takim wyzwaniom, Twój system dokumentacji idealnie wspiera Cię za pomocą glosariusza, w którym możesz zdefiniować ważne terminy raz i odwołać się do nich w dokumentacji. 

Porady: 

  • Używaj wyrazistych i spójnych nazw; 
  • Dokument od ogółu do szczegółu i najczęściej używany; 
  • Zwykle wystarczy jedno zdanie; 
  • Spraw, aby dokumentacja stała się częścią procesu rozwoju; 
  • Użyj definicji w przewodniku biznesowym; 

Komentarze

Dodaj komentarz

Twój adres e-mail nie zostanie opublikowany. Wymagane pola są oznaczone *