Systemów TAGÓW (PL)
Proponowany główny system tagów
A. Status artykułu
To mówi, na jakim etapie jest treść.
status = idea — pomysł / szkic tematu
status = draft — wersja robocza
status = in_progress — ktoś aktywnie nad tym pracuje
status = review — gotowe do sprawdzenia merytorycznego
status = approved — zaakceptowane
status = published — ukończone i gotowe do użycia
status = obsolete — przestarzałe
status = archived — archiwum
To jest najważniejszy tag całego systemu.
B. Priorytet
To mówi, co trzeba skończyć najpierw.
priority = p0 — krytyczne / natychmiast
priority = p1 — bardzo ważne
priority = p2 — normalne
priority = p3 — niskie
priority = backlog — kiedyś, bez ciśnienia
Polecam p0–p3, bo jest krótkie, jednoznaczne i dobrze sortuje się “w głowie”.
C. Stan tłumaczenia
To mówi, czy istnieje wersja w innym języku i na jakim jest etapie.
Najpraktyczniej per język, np.:
lang = pl — język bieżącego artykułu
i18n_en = missing — brak wersji EN
i18n_en = draft — tłumaczenie rozpoczęte
i18n_en = translated — przetłumaczone
i18n_en = review — czeka na sprawdzenie tłumacza
i18n_en = verified — sprawdzone przez tłumacza
i18n_en = synced — zgodne z aktualną wersją źródłową
Analogicznie:
i18n_de = missing / translated / verified / synced
i18n_fr = ...
To jest lepsze niż jeden ogólny tag translation = yes/no, bo od razu widzisz dla którego języka jest problem.
D. Zgodność tłumaczenia z oryginałem
To warto rozdzielić od samego faktu przetłumaczenia.
translation_check = pending
translation_check = verified
translation_check = needs_update
Ale jeszcze lepiej robić to per język, np.:
check_en = pending
check_en = verified
check_en = needs_update
To dokładnie odpowiada temu, o co pytasz: czy odpowiednik w innym języku został już sprawdzony przez tłumacza.
3. Co dorzuciłbym od siebie
E. Właściciel artykułu
Żeby zawsze było wiadomo, kto odpowiada za dokończenie.
owner = marek
owner = docs-team
owner = anna
Bez tego statusy bardzo szybko stają się martwe.
F. Typ treści
To pomaga rozróżnić, co to za artykuł.
type = guide
type = tutorial
type = faq
type = reference
type = policy
type = release_note
type = troubleshooting
To potem bardzo pomaga w wyszukiwaniu i raportowaniu.
G. Przegląd okresowy
Dla dokumentacji technicznej to bardzo przydatne.
review_cycle = monthly
review_cycle = quarterly
review_cycle = yearly
oraz dodatkowo:
review_due = 2026-06
reviewed_at = 2026-04-07
BookStack dobrze nadaje się do takich metadanych w tagach. Oficjalna dokumentacja nawet podaje podobny przykład z datą przeglądu jako wartością tagu.
H. Ryzyko / blokery
Żeby było widać, czemu coś stoi.
blocker = none
blocker = legal
blocker = product_info
blocker = translation
blocker = review
blocker = screenshots
To jest bardzo praktyczne przy pracy zespołowej.
I. Poziom kompletności
Dobre, jeśli macie dużo niedokończonych stron.
completeness = 10
completeness = 50
completeness = 80
completeness = 100
albo prościej:
completeness = low
completeness = medium
completeness = high
Instrukcja tagowania artykułów w BookStack
Cel
Celem tagowania jest szybkie określenie:
Tagi mają być jednoznaczne, krótkie i spójne.
Nie używamy własnych wariantów ani synonimów.
Zasada ogólna
Każdy tag zapisujemy w formie:
nazwa = wartość
Przykład:
status = review
Nie używamy tagów opisowych typu:
ważne
pilne
do poprawy
angielski gotowy
Zamiast tego zawsze używamy ustalonego schematu pól.
Tagi obowiązkowe
Każdy artykuł powinien mieć co najmniej poniższe tagi.
1. Status artykułu
Tag:
status = ...
Dozwolone wartości:
idea — sam pomysł, temat do opracowania
draft — szkic / wersja robocza
in_progress — artykuł jest aktualnie opracowywany
review — gotowy do sprawdzenia
approved — zaakceptowany
published — gotowy i zakończony
obsolete — nieaktualny
archived — archiwalny
Zasada
Artykuł powinien mieć tylko jeden tag status.
2. Priorytet
Tag:
priority = ...
Dozwolone wartości:
p0 — krytyczne, do zrobienia natychmiast
p1 — bardzo ważne
p2 — standardowy priorytet
p3 — niski priorytet
backlog — do zrobienia kiedyś, bez terminu
Zasada
Artykuł powinien mieć tylko jeden tag priority.
3. Język artykułu głównego
Tag:
lang = ...
Przykładowe wartości:
pl
en
de
fr
Zasada
Ten tag określa, w jakim języku jest bieżący artykuł.
4. Właściciel artykułu
Tag:
owner = ...
Przykładowe wartości:
anna
marek
docs-team
support-team
Zasada
Każdy artykuł musi mieć wskazaną osobę albo zespół odpowiedzialny za jego utrzymanie.
Tagi tłumaczeń
Te tagi stosujemy wtedy, gdy artykuł ma lub powinien mieć odpowiednik w innym języku.
5. Status tłumaczenia dla konkretnego języka
Tag:
translation_<język> = ...
Przykłady:
translation_en = missing
translation_en = draft
translation_en = translated
translation_en = review
translation_en = verified
translation_en = synced
Dozwolone wartości:
missing — brak tłumaczenia
draft — tłumaczenie rozpoczęte
translated — przetłumaczone
review — czeka na sprawdzenie
verified — sprawdzone przez tłumacza
synced — zgodne z aktualną wersją źródłową
Zasada
Dla każdego języka używamy osobnego tagu, np.:
translation_en = verified
translation_de = missing
6. Status sprawdzenia tłumaczenia
Jeżeli zespół chce rozdzielać „przetłumaczone” od „sprawdzone przez tłumacza”, można stosować dodatkowy tag:
check_<język> = ...
Przykłady:
check_en = pending
check_en = verified
check_en = needs_update
Dozwolone wartości:
pending — jeszcze niesprawdzone
verified — sprawdzone
needs_update — wymaga ponownej weryfikacji po zmianach
Zasada
Jeśli używany jest tag check_<język>, to powinien dotyczyć tylko języków, dla których tłumaczenie już istnieje.
Tagi dodatkowe
Te tagi nie są obowiązkowe, ale są bardzo przydatne.
7. Typ treści
Tag:
type = ...
Dozwolone wartości:
guide
tutorial
faq
reference
policy
troubleshooting
release_note
Zasada
Pomaga odróżnić instrukcję od polityki, FAQ albo notatki referencyjnej.
8. Termin przeglądu
Tag:
review_due = ...
Format:
YYYY-MM
Przykłady:
review_due = 2026-05
review_due = 2026-12
Zasada
Stosujemy do treści, które trzeba regularnie sprawdzać.
9. Blokery
Tag:
blocker = ...
Dozwolone wartości:
none
review
translation
legal
product_info
screenshots
approval
Zasada
Używamy tylko wtedy, gdy coś realnie blokuje ukończenie artykułu.
Minimalny wymagany zestaw tagów
Każdy nowy artykuł powinien mieć minimum:
status
priority
lang
owner
Jeżeli artykuł ma wersję w innym języku, dokładamy także:
translation_<język>
opcjonalnie check_<język>
Przykłady poprawnego tagowania
Przykład 1 — szkic artykułu po polsku
status = draft
priority = p2
lang = pl
owner = anna
type = guide
Przykład 2 — ważny artykuł w trakcie pracy, brak EN
status = in_progress
priority = p0
lang = pl
owner = docs-team
type = troubleshooting
translation_en = missing
Przykład 3 — artykuł gotowy, angielska wersja sprawdzona
status = published
priority = p2
lang = pl
owner = marek
type = reference
translation_en = verified
check_en = verified
Przykład 4 — artykuł nieaktualny
status = obsolete
priority = backlog
lang = en
owner = support-team
type = faq
Zasady nazewnictwa
1. Używamy tylko małych liter
Poprawnie:
status = in_progress
Niepoprawnie:
Status = In Progress
2. Spacje tylko wokół znaku =
Poprawnie:
priority = p1
Niepoprawnie:
priority=p1priority = p1
3. Nie używamy polskich znaków w nazwach tagów
Poprawnie:
translation_en
Niepoprawnie:
tłumaczenie_en
4. Nie tworzymy własnych wariantów wartości
Poprawnie:
review
Niepoprawnie:
to_review
checked_later
needs-check
weryfikacja
5. Jeden tag = jedna rola
Nie mieszamy pojęć.
Przykład:
status mówi o etapie pracy
priority mówi o ważności
translation_en mówi o stanie tłumaczenia
check_en mówi o stanie weryfikacji tłumaczenia
Czego nie robimy
Nie używamy takich tagów:
ważne
pilne
do zrobienia
angielski
gotowe
prawie gotowe
ktoś robi
sprawdzone chyba
Powód: są niejednoznaczne i po czasie przestają być użyteczne.
Zalecany workflow
Nowy artykuł
Na starcie ustawiamy:
status = draft
priority = p2
lang = pl
owner = <osoba/zespół>
Artykuł opracowywany
Zmieniamy:
status = in_progress
Artykuł gotowy do sprawdzenia
Zmieniamy:
status = review
Artykuł zatwierdzony
Zmieniamy:
status = approved
albo, jeśli już końcowy:
status = published
Gdy potrzebne tłumaczenie
Dodajemy np.:
translation_en = missing
Potem w miarę postępu:
translation_en = draft
translation_en = translated
translation_en = verified
translation_en = synced
Gdy artykuł przestaje być aktualny
Zmieniamy:
status = obsolete
Wersja skrócona dla zespołu
Każdy artykuł musi mieć:
status
priority
lang
owner
Jeśli dotyczy tłumaczeń, dodajemy:
translation_<język>
opcjonalnie check_<język>
Dozwolone dodatkowe pola:
type
review_due
blocker
Nie tworzymy własnych nazw ani własnych wartości.