3.4 KiB
| title | author | date |
|---|---|---|
| System zarządzania dokumentami | Robert Bendun | 05.11.2020 |
| Wersja | Data | Autorzy | Opis zmian |
|---|---|---|---|
| 1.0.0 | 05.11.2020 | Robert Bendun | Stworzenie dokumentu |
Podsumowanie
Poniższy dokument opisuje sposób zarządzania oraz tworzenia dokumentów w ramach systemu, w którym się znajduje.
Miejsce przechowywania dokumentów
Dokumenty są przechowywane w repozytoriach GIT. Powinny istnieć 3 repozytoria, różniące się dostępnością odczytu oraz zapisu. Repozytoria mogą się znajdować w serwisach takich jak Github czy Gitlab lub na prywatnym serwerze tworzących oprogramowanie oraz dokumenty z nim powiązane.
Zdefiniowane są 3 różne branche:
- Draft - modyfikuje dowolna jednostka zaangażowana w projekt. Miejsce opracowywania dokumentów
- Review - modyfikuje wyłącznie grupa wyznaczona do utrzymywania dokumentacji. Pozostałe osoby mogą wykonywać pull requesty jako uwagi do projektu.
- Official - modyfikuje wyłącznie grupa wyznaczona do utrzymywania dokumentacji. Zmiany powinny być przenoszone z brancha Review. (branch domyślny)
Każde z powyższych branchy powinno być powszechnie dostępne do odczytu dla osób tworzących projekt. Dokument podstawowo powinien być przechowywany wewnątrz brancha Draft. W przypadku potrzeby, można dodać automatyczne generowanie dokumentów DjVu czy HTML w celu ułatwienia dostępu do repozytorium Official.
Używane formaty plików
Formaty plików używane wewnątrz systemu powinny koniecznie musi posiadać możliwość modyfikacji przy pomocy wolnego oprogramowania. Używanie formatów zamkniętoźródłowych jest nieporządane i powinno być unikane w ramach możliwości. Wybór takiego rozwiązania umożliwa swobodną edycję oraz odczyt dokumentów niezależnie od posiadanych licencji oraz statusu projektu. Zamiast wygenerowanych dokumentów z plików źródłowych, należy dołączać pliki źródłowe. Przykładowo, zamiast dołączać wygenerowany dokument w postaci pliku DjVu, powinno się dołączyć dokument źródłowy, z którego wygenerowano dokument DjVu. Pliki tekstowe powinny być zakodowane w UTF-8.
Przykładowe formaty plików:
- dokumenty: Markdown, LaTeX
- wykresy, pliki graficzne: pliki programu GIMP, SVG (preferowany), PostScript, DjVu
Sposób tworzenia dokumentów
Preferowanymi formatami są Markdown oraz LaTeX. Każdy dokument powinien posiadać stronę tytułową, ze zdefiniowanymi:
- tytułem
- autorami dokumentu
- datą ostatniej modyfikacji
Kolejna powinna być zdefiniowana tabela wersji dokumentu, z następującymi kolumnami:
- wersja wg wymagań wersjonowania semantycznego
- data
- autorzy danej wersji
- opis zmian
Następnym koniecznym elementem jest podsumowanie, opisujące w krótki sposób zawartość dokumentu.
Zasady nazewnictwa plików
Pliki powinny zostać zapiswane w notacji kebab-case. Powinno się unikać wersjonowania plików wewnątrz nazw, na rzecz opisów commitów oraz tagów w systemie GIT. Pliki powinny zawierać rozszerzenia umożliwające rozpoznanie formatu zapisu pliku.
Łączenie różnych modyfikacji dokumentów
Jest analogiczne do łączenia różnych wersji kodu w systemie GIT. Zapobiega to wystąpieniu dwóch wersji i przypadkowym zastąpieniu wersji nowszej od wersji źródłowej modyfikacji.