Jak pisać pomoc

Ta strona jest instrukcją dla piszących, nie dla korzystających. Polecenie, z którego moduł powstał, brzmiało: „tam opisujemy wszystkie funkcje", „przepływy", „aby wszystkie zmiany tam wprowadzać". Reguła jest więc prosta: zmiana funkcji i zmiana jej opisu idą w jednym commicie.

Gdzie leży treść

src/pomoc/
  nawigacja.ts     kolejność stron i podział na rozdziały
  strony.ts        wczytanie treści, spis treści, wyszukiwarka
  tresc/*.md       SAMA TREŚĆ — po jednym pliku na stronę

Treść nie leży w bazie i nie jest zaszyta w kodzie. Leży w plikach Markdown w repozytorium, więc poprawka opisu jest zwykłym diffem obok poprawki kodu.

Dodanie strony

1. Utwórz src/pomoc/tresc/<id>.md. Pierwszy nagłówek # staje się tytułem strony w nawigacji.
2. Dopisz <id> do właściwego rozdziału w src/pomoc/nawigacja.ts.

Nic więcej. Spis treści po prawej i wyszukiwarka liczą się z treści same.

Nazwa pliku idzie bez ogonków, człony myślnikiem — jak reszta plików w projekcie. Sam tekst strony pisze się z pełnymi polskimi znakami.

Składnia

Obsługiwany jest podzbiór Markdown, który wystarcza do dokumentacji:

Odnośniki wewnętrzne

Do innej strony pomocy prowadzi przedrostek pomoc::

[Projekty](/docs/narzedzia-wspolne/projekty)
[Import GML](/docs/przeplywy/przeplywy#przeplyw-importu-gml)

Kotwica to tytuł nagłówka bez ogonków, małymi literami, z myślnikami zamiast spacji. Odnośnik zewnętrzny pisze się zwyczajnie i otwiera w nowej karcie.

Osadzony graf FLOW

Blok kodu o języku flow wstawia żywy graf katalogu — ten sam komponent, który rysuje zakładkę FLOW w module S-Base. Treścią bloku jest nazwa rejestru albo nic (cały katalog):

​> **Graf FLOW** — w aplikacji w tym miejscu rysuje się żywy graf katalogu (GESUT
​); dokumentacja statyczna go nie osadza.

Osadzamy istniejący graf, a nie rysujemy drugiego — i nie wstawiamy zrzutów ekranu, bo obrazek zestarzeje się przy pierwszej zmianie słowników.

Zasady treści

• Opisujemy stan faktyczny, nie plan. Funkcja, której nie ma, należy do sekcji „Ograniczenia", a nie do listy możliwości.
• Sekcja „Ograniczenia" jest obowiązkowa wszędzie tam, gdzie moduł ma granice. Uczciwość co do granic jest częścią dokumentacji; pomoc, która obiecuje za dużo, kosztuje więcej niż jej brak.
• Nazwy własne cytujemy dosłownie — kody obiektów, nazwy paneli, przycisków i formatów tak, jak stoją w aplikacji.
• Bez zrzutów ekranu. Zrzut nie przechodzi kontroli jakości i starzeje się w ciszy.

Strona docs.ai-xis.com

Ta sama treść jest publikowana jako osobna strona dokumentacji pod adresem https://docs.ai-xis.com (Fumadocs, katalog dokumentacja/ w repozytorium). Strona nie ma własnej kopii tekstu: generator dokumentacja/narzedzia/zloz-tresc.mjs składa ją z plików src/pomoc/tresc/*.md i kolejności z nawigacja.ts przed każdym budowaniem. Reguła „zmiana funkcji i opisu w jednym commicie" obejmuje więc obie strony naraz.

• Odnośniki pomoc:<id> zamieniają się na adresy stron; blok flow na stronie statycznej jest tylko uwagą, że żywy graf rysuje aplikacja.
• Strona start jest stroną główną dokumentacji.
• Wdrożenie: npm run dokumentacja:wdroz (build na stanowisku, na hosting jedzie gotowy wynik). Wydanie aplikacji nie publikuje dokumentacji samo — po zmianie treści trzeba uruchomić to polecenie.

Przegląd tygodniowy

Pomoc starzeje się cicho: kod idzie dalej, opis zostaje. Raz w tygodniu sprawdza to zadanie harmonogramu stanowiska — npm run pomoc:tygodniowo. Z ręki uruchamia się tak samo, a -- --sucho robi sam przegląd, bez wdrożenia.

Zadanie robi trzy rzeczy:

1. Wskazuje strony, które zostały w tyle. Każda strona ma w src/pomoc/przeglad.ts przypisany kod, który opisuje. Gdy ten kod ma commit młodszy niż plik opisu, strona trafia na listę do przejrzenia wraz z liczbą dni i nazwami zmienionych katalogów.
2. Składa treść dokumentacji na nowo — ten sam generator, co przed budowaniem; rozjazd nawigacji z plikami wychodzi od razu.
3. Wdraża docs.ai-xis.com, o ile drzewo robocze jest czyste. Brudne drzewo kończy na przeglądzie: wystawienie opisu funkcji, która jeszcze nie jest gotowa, byłoby gorsze niż tydzień opóźnienia.

Wynik każdego przebiegu zostaje jako raport w raporty/RRRRMMDD/.

To wskazanie, nie wyrok. Zmiana w kodzie mogła nie dotknąć niczego, co opis obiecuje — wtedy stronę zostawia się bez zmian. Czego zadanie nie robi i nie będzie robić: nie pisze treści. Opis działania powstaje przy zmianie funkcji, w tym samym commicie; przegląd jest tylko siatką bezpieczeństwa na to, co się przez tę regułę przecisnęło.

Dodanie strony wymaga wpisu w mapie źródeł — nowa pozycja w nawigacja.ts bez wpisu w ZRODLA_STRON zatrzymuje testy, żeby przegląd nie przestał po cichu patrzeć na nowy moduł.