Jak automatycznie aktualizować dokumentację przy każdym wydaniu

Zaktualizowano 3 listopada 2026

Aby automatycznie aktualizować dokumentację przy każdym wydaniu, uruchom zadanie dokumentacyjne bezpośrednio z wydania: opublikowanego wydania GitHub, zdarzenia wydania GitLab, tagu Bitbucket lub nowego wpisu w publicznym dzienniku zmian. Zadanie odczytuje informacje o wydaniu, znajduje strony pomocy i filmy, których dotyczy zmiana, przygotowuje poprawki i wysyła je do zatwierdzenia przez odpowiednią osobę. W przypadku dokumentacji dla klientów ten krok weryfikacji zapewnia bezpieczeństwo automatyzacji.

Ten przewodnik przeprowadzi Cię przez ten proces z dowolnym narzędziem (GitHub Actions, GitLab, Bitbucket, strona z dziennikiem zmian), a następnie pokaże, jak Autopilot Clevera wykonuje tę samą pętlę dla centrum pomocy z filmami.

Czym jest ciągła dokumentacja?#

Swimm, firma która spopularyzowała ten termin, definiuje ciągłą dokumentację jako tworzenie i aktualizowanie dokumentacji przyrostowo w ramach przepływu pracy programistycznej, zamiast sporadycznych projektów nadrabiania zaległości. Większość narzędzi zbudowanych na tej idei, często sprzedawanych jako "samouaktualniająca się dokumentacja", monitoruje commity lub pull requesty i aktualizuje dokumentację programistyczną obok kodu.

Centra pomocy dla klientów potrzebują innego wyzwalacza. Czytelnicy nie widzą commita; widzą wydanie. Tabela przedstawia kompromisy.

Argumentem za automatyzacją jest tempo. Badanie DORA State of DevOps z 2021 roku wykazało, że elitarne zespoły wdrażają zmiany 973 razy częściej niż zespoły o niskiej wydajności. Nie każde wdrożenie zmienia to, co widzą czytelnicy, ale zespoły wydają oprogramowanie znacznie częściej, niż ktokolwiek jest w stanie ręcznie sprawdzić artykuły. To samo badanie wykazało, że zespoły z wysokiej jakości dokumentacją były 3,8 razy bardziej skłonne do wdrażania najlepszych praktyk bezpieczeństwa, więc dokumentacja nie jest kwestią drugorzędną. A nieaktualna dokumentacja to powszechny problem: w ankiecie GitHub Open Source Survey z 2017 roku 93% respondentów napotkało niekompletną lub nieaktualną dokumentację, a 60% współtwórców stwierdziło, że rzadko lub nigdy nie wnosi wkładu do dokumentacji.

Krok 1: Pisz informacje o wydaniu, które może wykorzystać zadanie dokumentacyjne#

Automatyzacja może aktualizować dokumentację tylko tak dobrze, jak dobrze informacje o wydaniu opisują zmianę. Pomagają dwie konwencje.

• Grupuj zmiany według typu. Keep a Changelog używa kategorii Added, Changed, Deprecated, Removed, Fixed i Security. "Added" zazwyczaj oznacza nowy artykuł lub film; "Changed" i "Removed" oznaczają, że istniejąca treść jest teraz błędna.
• Oddziel to, co widzą użytkownicy, od tego, czego nie widzą. Automatycznie generowane informacje o wydaniu w GitHub sortują scalone pull requesty według etykiety w .github/release.yml i mogą całkowicie wykluczyć niektóre etykiety.

# .github/release.yml
changelog:
  exclude:
    labels: [internal, chore]
  categories:
    - title: New
      labels: [feature]
    - title: Changed in the app
      labels: [ui-change]
    - title: Fixes
      labels: [bug]
    - title: Other changes
      labels: ["*"]

Etykieta "ui-change" jest najbardziej przydatną etykietą do dodania: informuje zadanie dokumentacyjne, które elementy mogą zepsuć artykuł. Nazwij ekran również w tytule pull requesta ("Ustawienia rozliczeń: przenieś przypomnienia do Automatyzacji"), aby zmianę można było dopasować do stron, na których wyświetlany jest ten ekran.

Krok 2: Automatyczna aktualizacja dokumentacji przy wydaniu: uruchom zadanie#

Każdy główny host Git może uruchomić zadanie, gdy publikujesz wydanie, co pozwala generować aktualizacje dokumentacji z wydań GitHub lub ich odpowiedników w GitLab i Bitbucket. Szczegóły się różnią.

W GitHub minimalny workflow wygląda tak:

# .github/workflows/docs-on-release.yml
name: Docs on release
on:
  release:
    types: [published]
permissions:
  contents: read
jobs:
  draft-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          persist-credentials: false
      - name: Draft docs updates for this release
        env:
          TAG: ${{ github.event.release.tag_name }}
          NOTES: ${{ github.event.release.body }}
        run: ./scripts/draft-docs-updates.sh

Użyj published zamiast created: zgodnie z dokumentacją zdarzeń GitHub, created nie uruchamia się dla wydań roboczych, podczas gdy published obejmuje zarówno stabilne wydania, jak i wersje przedpremierowe. Przekaż informacje o wydaniu przez zmienną środowiskową, jak powyżej, a nie bezpośrednio do polecenia powłoki, ponieważ tekst wydania jest danymi wejściowymi użytkownika. A jeśli narzędzie takie jak release-please lub semantic-release tworzy Twoje wydania za pomocą domyślnego tokena, zdarzenia, które wywołuje, nie uruchomią Twojego workflow dokumentacyjnego; zamiast tego przekaż temu narzędziu token GitHub App lub osobisty token dostępu.

W GitLab i Bitbucket odpowiednikiem jest zadanie uruchamiane na tagach:

# .gitlab-ci.yml
draft-docs:
  rules:
    - if: $CI_COMMIT_TAG
  script:
    - ./scripts/draft-docs-updates.sh "$CI_COMMIT_TAG"

# bitbucket-pipelines.yml
pipelines:
  tags:
    'v*':
      - step:
          script:
            - ./scripts/draft-docs-updates.sh "$BITBUCKET_TAG"

Krok 3: Znajdź strony i filmy, których dotyczy każde wydanie#

To krok, który pomija większość poradników i który decyduje o tym, czy automatyzacja pomaga. Informacja o wydaniu mówi: "Przypomnienia przeniesione do Rozliczenia → Automatyzacje"; Twoje zadanie musi zamienić to na "te trzy artykuły i dwa filmy są teraz błędne".

Trzy metody, od najprostszej do najskuteczniejszej:

1. Wyszukaj zmienione etykiety. Wyciągnij każdy cytowany ciąg znaków interfejsu z informacji o wydaniu i przeszukaj swoje artykuły oraz skrypty filmów pod kątem starego brzmienia.
2. Prowadź inwentarz ekranów. Oznacz każdy artykuł i film ekranami, które pokazuje, i dopasuj do nich nazwy ekranów z tytułów pull requestów. Nasz przewodnik po utrzymywaniu dokumentacji w aktualnym stanie zawiera szablon inwentarza.
3. Pozwól modelowi przeczytać każdego kandydata w całości. Podaj modelowi językowemu informacje o wydaniu oraz pełny tekst (lub transkrypcję) każdej strony kandydującej i poproś o werdykt: nadal poprawne, wymaga poprawki tekstu lub wymaga nowych zrzutów ekranu lub nagrań. Przeczytanie całej strony ma znaczenie, ponieważ zepsuty krok często nie jest tym, który wymienia informacja o wydaniu.

Prompt dla takiego werdyktu może być krótki:

You check help articles against a software release.
Release notes: {release_notes}
Article ({url}): {article_text}

Answer in JSON: {"verdict": "still_right" | "text_fix" | "new_screenshots_or_footage",
"reason": "<one sentence quoting the release item>",
"changed_steps": [<step numbers>]}
Only use facts from the release notes. If unsure, answer "text_fix" and say why.

Krok 4: Przygotuj aktualizacje#

W przypadku tekstu przygotowanie wersji roboczej jest łatwe: model otrzymuje informacje o wydaniu, bieżący artykuł i Twoje zasady stylu, a następnie zwraca poprawioną wersję. Zachowaj identyfikator i adres URL artykułu, aby aktualizować istniejącą stronę zamiast tworzyć niemal duplikat, i zapisz, które wydanie ostatnio go zmieniło. Zasady w jak pisać artykuły do centrum pomocy stanowią dobry prompt dotyczący stylu.

Zrzuty ekranu i filmy są trudniejsze. Model nie może wyprodukować zrzutu ekranu, którego nie widział. Możesz albo przechwycić nowe obrazy w swoim zestawie testów interfejsu, ponownie nagrać zmieniony przepływ, albo oznaczyć element do ponownego nagrania przez człowieka. Oznacz każdy element w planie: poprawka tekstu, nowy zrzut ekranu lub ponowne nagranie. Gdy zmieniony przepływ zostanie nagrany, przekształcenie nagrania w dokumentację daje nowe kroki i zrzuty ekranu w jednym przejściu.

Krok 5: Postaw człowieka między wersją roboczą a czytelnikiem#

Opisy pull requestów są pisane przez wiele osób i nigdy nie są sprawdzane z myślą o klientach. Traktuj je, oraz informacje o wydaniu, jako niezaufane dane wejściowe: mogą zawierać instrukcje, które model wykona. Wysyłaj każdą wersję roboczą do weryfikacji.

• Kto zatwierdza: lider wsparcia lub dokumentacji dla treści centrum pomocy, inżynier dla dokumentacji API.
• Co pokazuje dobra weryfikacja: każdą dotkniętą stronę z porównaniem przed i po, element wydania, który ją spowodował, oraz jasną listę "brak zmian", aby recenzenci ufali temu, co zostało pominięte.
• Co publikować automatycznie: początkowo nic, co jest skierowane do klienta. Gdy kilka wydań przejdzie bez niespodzianek, możesz poluzować zasadę dla elementów niskiego ryzyka, takich jak poprawki literówek.

Która konfiguracja pasuje do Twojego zespołu?#

Jeśli Twój zespół pracuje już w Claude Code, możesz również poprosić go o aktualizację dokumentacji po wydaniu przez MCP; omawiamy to w jak aktualizować dokumentację za pomocą Claude Code po każdym wydaniu.

Jak automatycznie aktualizować dokumentację przy wydaniu za pomocą Clevera Autopilot#

Clevera to platforma AI, która zamienia nagranie ekranu w narracyjny film instruktażowy, artykuł pomocy krok po kroku oraz stronę w Twoim centrum pomocy, w 74 językach. Funkcja Autopilot, dostępna w planach Pro i Custom, wykonuje kroki od 2 do 5 powyżej dla centrum pomocy Clevera.

• Wyzwalacz. Przepis Utrzymuj moje centrum pomocy w aktualnym stanie, gdy publikujemy zmiany monitoruje Wydania lub Scalone zmiany w repozytorium, albo Stronę z informacjami o zmianach czytaną codziennie lub co tydzień. GitHub łączy się za pomocą aplikacji tylko do odczytu; GitLab (gitlab.com) i Bitbucket Cloud łączą się w ten sam sposób, jeśli jest to dostępne. Clevera sprawdza repozytorium mniej więcej raz na godzinę. Czyta notatki z wydań, tagi oraz tytuły i opisy pull requestów, nigdy nie zagląda do Twojego kodu.
• Dopasowanie. Każde uruchomienie sprawdza do 40 filmów i artykułów w centrum pomocy i czyta każde z nich w całości.
• Tworzenie szkiców. Każdy element otrzymuje werdykt: nadal poprawny, poprawka tekstu pokazana przed i po, lub nagraj ponownie z nowymi krokami. Ponowne nagranie wymaga Użyj mojej aplikacji: adresu Twojej aplikacji oraz, jeśli jest to wymagane, logowania (najlepiej sprawdza się konto testowe). Nowy film zastępuje stary pod tym samym linkiem, więc podobnie jak w przypadku edycji LiveSync, osadzenia i strony centrum pomocy wyświetlają go bez nowych linków.
• Przegląd. Każde uruchomienie czeka na Ciebie. Odznaczasz to, czego nie chcesz, i klikasz Uruchom, lub klikasz Poproś o zmiany, aby uzyskać nowy plan. Plan wygasa po siedmiu dniach, a kolejne uruchomienie uwzględnia wszystko, co wydarzyło się od tego czasu.

Monitorowanie i planowanie są bezpłatne; każda linia planu pokazuje swoje kredyty, a typowe uruchomienie kosztuje od 10 do 150 kredytów. Ta sama pętla jest dostępna dla filmów bez centrum pomocy dzięki Aktualizuj moje filmy, gdy produkt się zmienia, a Nagraj film dla każdej nowej funkcji proponuje nowy poradnik dla tego, co dodaje każde wydanie (zobacz jak zrobić film z informacjami o wydaniu dla wersji ręcznej).

Gdzie Clevera nie jest odpowiednim narzędziem: nie generuje dokumentacji API z kodu ani nie pisze Twojego CHANGELOG.md. W tym zakresie zobacz nasze porównanie generatorów changelogów AI lub serwerów MCP dla dokumentacji, jeśli chcesz, aby agent AI edytował dokumentację na innej platformie.

Zacznij za darmo, aby najpierw zbudować centrum pomocy i filmy; Autopilot jest dostępny w planie Pro. Kroki konfiguracji znajdują się w artykule pomocy Połącz GitHub lub inne repozytorium z Autopilotem.

FAQ#

Czy dokumentacja może aktualizować się automatycznie, gdy publikujemy wydanie?#

Wykrywanie i tworzenie szkiców może być automatyczne: wydanie uruchamia zadanie, które znajduje zmienione strony i przygotowuje poprawki. Publikacja powinna pozostać decyzją człowieka w przypadku dokumentacji skierowanej do klientów, ponieważ notatki z wydań nie zawsze mówią wprost, co zamierzałeś, aby czytelnicy zrobili.

Czy dokumentację należy aktualizować przy każdym commicie czy przy każdym wydaniu?#

W przypadku centrów pomocy – przy każdym wydaniu. Commity i pull requesty zmieniają się nieustannie i często znajdują się za flagami funkcji; wydanie to moment, w którym czytelnicy faktycznie widzą zmianę. Dokumentacja deweloperska, która znajduje się obok kodu, może podążać za pull requestami.

Jak wyzwolić GitHub Action, gdy publikowane jest wydanie?#

Użyj on: release z types: [published]. Jeśli wydanie jest tworzone przez inny workflow przy użyciu domyślnego GITHUB_TOKEN, nie uruchomi to Twojego workflow; użyj tokena GitHub App lub osobistego tokena dostępu dla narzędzia wydawniczego.

Co jeśli nie publikujemy wydań na GitHubie?#

Użyj sygnału, który masz: zdarzenia wydań GitLab, potoki tagów Bitbucket lub zaplanowane zadanie, które czyta Twoją publiczną stronę z informacjami o zmianach lub jej kanał RSS. Autopilot Clevera może monitorować stronę z informacjami o zmianach codziennie lub co tydzień właśnie w takim przypadku.

Czy zrzuty ekranu i filmy również mogą być aktualizowane automatycznie?#

Zrzuty ekranu mogą być przechwytywane w testach UI przy każdej kompilacji. Filmy wymagają ponownego nagrania zmienionego przepływu; rejestrator AI może ponownie uruchomić zapisaną instrukcję w nowym interfejsie, a Autopilot może to zrobić dla filmów Clevera, gdy podasz mu adres swojej aplikacji (i dane logowania, jeśli aplikacja ich wymaga). Obejrzyj nowe nagranie przed jego zatwierdzeniem.