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

To mówi, na jakim etapie jest treść.
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:To mówi, co trzeba skończyć najpierw.

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 ciśnienia / 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:Żeby zawsze było wiadomo, kto odpowiada za dokończenie. Chociaż może dokończyć taki artykuł także inny edytor, lub grupa edytorów.

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 = guideVENATOR

---

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.3. Nie tworzymy własnych wariantów wartości

Poprawnie:

review

Niepoprawnie:

• to_review
• checked_later
• needs-check
• weryfikacja

---

5.4. 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.