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ą:
POZIOM | NAZWA | 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 |
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;
Dodaj komentarz