Systemów TAGÓW dla STRON (PL)

Proponowany główny system tagów dla STRON

System tagów dla PÓŁEK i KSIĄŻEK zostanie opracowany póżniej

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:

• na jakim etapie jest artykuł,
• jak pilne jest jego dokończenie,
• kto za niego odpowiada,
• czy istnieje wersja w innym języku,
• czy tłumaczenie zostało już sprawdzone,
• czy artykuł wymaga przeglądu po pewnym czasie lub jest czymś zablokowany.

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, opisanego poniżej

---

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
• p4 — 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
• ro
• hu

Zasada

Ten tag określa, w jakim języku jest bieżący artykuł. 

UWAGA!   Być może IVSTVS zaprojektuje nam tak system, że nie trzeba będzie tego używać za jakiś czas

---

4. Właściciel artykułu

Tag:

owner = ...

Przykładowe wartości, to cognomeny = jednowyrazowe loginy edytorów:

• CARBO
• CACAIVS
• VENATOR

Zasada

Każdy artykuł musi mieć wskazaną osobę odpowiedzialną za jego utrzymanie.

Być może wprowadzimy z czasem odpowiedzialne zespoły edytorów

---

Tagi tłumaczeń   

UWAGA !   Na razie nie stosować. Zostanie to skonsultowane z programistą

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=p1
priority = 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.