[Intum Pomoc](https://intum.pl/pomoc.md) / [Dobre praktyki](https://intum.pl/pomoc/baza-wiedzy/dobre-praktyki.md)

# [Jak pisać wpisy](https://intum.pl/pomoc/baza-wiedzy/jak-pisac-wpisy-bazy-wiedzy.md)

Czytelnik bazy wiedzy nie czyta, tylko szuka. Przychodzi z konkretnym problemem, przegląda
tytuły i nagłówki, a gdy w kilka sekund nie zobaczy swojej sprawy, wychodzi i pisze do
supportu. Dobry wpis jest napisany pod takie szybkie szukanie.

> [!PATH]
> [Baza wiedzy → Wpisy](app:/kb/entries) → **Dodaj wpis**

## Tytuł słowami klienta

Tytuł to pierwsza rzecz, którą widzi wyszukiwarka bazy, asystent AI i Google. Pisz go tak, jak
klient opisałby problem, a nie tak, jak nazywa się funkcja w systemie:

| Zamiast | Lepiej |
|---|---|
| Moduł eksportu | Jak pobrać listę klientów do Excela |
| Uprawnienia | Jak dać pracownikowi dostęp tylko do faktur |
| Błąd 403 | Widzę komunikat „Brak dostępu" - co zrobić |

## Jeden wpis, jedno zadanie

„Ustawienia konta" jako jeden długi artykuł nie odpowiada na żadne konkretne pytanie. Pięć
krótkich wpisów („Jak zmienić hasło", „Jak dodać logo na fakturze"...) odpowiada na pięć.
Krótkie wpisy łatwiej też podpiąć jako [helplinki](baza-wiedzy/helplinki) i łatwiej je
aktualizować.

Wyjątek to długi przewodnik po całym procesie, np. „Pierwsze kroki". Wtedy podziel go na
nagłówki `##`. Czytelnik szybciej znajdzie swój fragment, a helplink może wskazać pojedynczą
sekcję.

## Zaczynaj od „po co"

Pierwsze dwa zdania mówią, co czytelnik osiągnie i kiedy mu się to przyda. Dopiero potem idą
kroki. Ktoś, kto trafił w zły artykuł, dowie się tego od razu, a nie po przeczytaniu całości.

## Kroki, nie opis ekranu

- **numeruj kroki**, gdy kolejność ma znaczenie; jeden krok to jedna czynność,
- **nazwy przycisków i pól pogrubiaj** i pisz dokładnie tak, jak są na ekranie,
- **pisz, co się stanie** po ostatnim kroku („Na liście pojawi się nowy klient") - to sposób
  czytelnika na sprawdzenie, że się udało,
- **zrzut ekranu dodawaj tam, gdzie trudno opisać miejsce**, a nie przy każdym kroku. Każdy
  zrzut trzeba będzie wymienić po zmianie wyglądu systemu.

## Trzy rodzaje wpisów

Większość wpisów to jeden z trzech rodzajów. Każdy ma inny kształt:

- **instrukcja** („Jak wystawić fakturę korygującą") - po co, co przygotować, kroki, efekt,
- **rozwiązanie problemu** („Faktura nie doszła do klienta") - objaw, najczęstsze przyczyny od
  najbardziej prawdopodobnej, co sprawdzić przy każdej i jak naprawić. Taki wpis najłatwiej
  zrobić z ticketu ([Wpisy z ticketów helpdesku](baza-wiedzy/wpisy-bazy-wiedzy-z-ticketow)),
- **wyjaśnienie** („Czym różni się szkic od faktury proforma") - pojęcie, przykład z życia,
  kiedy wybrać które. Bez kroków, za to z linkami do instrukcji.

## Linki i porządek

- **na końcu wpisu dodaj 2-3 powiązane wpisy** - następny logiczny krok, a nie wszystko,
  co jest na podobny temat ([Statusy, tagi i powiązania](baza-wiedzy/statusy-tagi-i-powiazania)),
- **link do ekranu systemu** zapisuj w formie `app:/ścieżka`, żeby czytelnik trafił prosto na
  swój ekran ([Szablon i wygląd](baza-wiedzy/szablon-i-wyglad-bazy-wiedzy)),
- **jedno słowo na jedną rzecz w całej bazie** - jeśli raz piszesz „kontrahent", nie pisz
  w innym wpisie „klient". Czytelnik uzna, że to dwie różne rzeczy, a asystent AI gorzej łączy
  wpisy.

## Przed publikacją

Przejdź instrukcję krok po kroku na swoim koncie, z wpisem otwartym obok. Pięć minut takiego
sprawdzenia wyłapuje więcej błędów niż czytanie tekstu. Wpis, który jeszcze czeka na
sprawdzenie, zaznacz jako **Prywatny**.