Jak jest zorganizowana dokumentacja NextPDF

W skrócie

Podręcznik NextPDF podlega ustalonemu kontraktowi. Każda strona ma jeden temat, jeden tryb Diataxis i jeden rodzaj strony. Każdy rodzaj strony ma wymagany zestaw nagłówków drugiego poziomu. Niewielki zestaw manifestów i bramek kontrolnych utrzymuje spójność struktury wraz z rozrastaniem się podręcznika.

Ta strona opisuje ten system, aby wkład trafił we właściwe miejsce. Pełny kontrakt normatywny, obejmujący dokładne listy nagłówków, reguły cytowania oraz procedurę podłączania bramek kontrolnych, znajduje się w wewnętrznym dokumencie zarządczym docs/style/expansion-standard.md. Najpierw przeczytaj tę stronę. Podczas tworzenia treści korzystaj z dokumentu wewnętrznego.

Wybór rodzaju strony

Stosuj te reguły po kolei, aby zdecydować, czy dodać stronę, czy rozszerzyć istniejącą:

1. Jeśli materiał stanowi odrębny temat, którego czytelnik nie spodziewałby się na istniejącej stronie, dodaj nową stronę.
2. Jeśli materiał uzupełnia temat, który należy już do istniejącej strony, rozszerz tę stronę.
3. Jeśli materiał to szczegółowe informacje, które nadmiernie rozbudowałyby stronę instalacji, szybkiego startu lub zadania, przenieś go na osobną stronę i utwórz do niej odnośnik.
4. W przeciwnym razie rozszerz istniejącą stronę.

Po ustaleniu, że strona powinna istnieć, ustaw jej tryb Diataxis. Tryb określa rodzaj strony:

• Samouczek prowadzi osobę uczącą się. Użyj przewodnika po zadaniach napisanego w formie przepisu.
• Instrukcja pomaga kompetentnemu czytelnikowi wykonać zadanie. Użyj przewodnika po zadaniach, przewodnika po serwerowym API lub przewodnika po zestawie programistycznym.
• Dokumentacja referencyjna podaje ścisłe informacje. Użyj dokumentacji referencyjnej API lub strony indeksowej.
• Wyjaśnienie pomaga zrozumieć temat. Użyj przewodnika dla programistów lub przewodnika po funkcjach premium.

Prosty język to podstawa każdego trybu, a nie osobny tryb.

Katalog rodzajów stron

Kontrakt podręcznika wyróżnia te rodzaje. Gdy strona zawiera tabelę API, zawsze wykorzystaj ponownie istniejący rodzaj. Nowy rodzaj wyłącznie etykietowy wprowadzaj tylko dla strony bez tabeli API.

• Rodzaje indeksowe: section-index, api-index, extension-index.
• Rodzaj referencyjny: api-reference. Wykorzystaj go ponownie dla każdej strony ze standardową tabelą API, w tym dla dokumentacji referencyjnej serwera oraz Python SDK.
• Rodzaj wyjaśniający: developer-guide. Wykorzystaj go ponownie dla treści dotyczących architektury, cyklu życia i punktów rozszerzeń, w tym dla przewodników serwera oraz Python SDK.
• Nowe rodzaje wyłącznie etykietowe: premium-feature-guide oraz task-guide, oba dla stron bez tabeli API.

Każda strona zaczyna się od nagłówka ## At a glance. Każda strona api-reference zawiera wspólną tabelę API oraz nagłówek Development notes. Wymagane nagłówki są nagłówkami drugiego poziomu, każdy w osobnym wierszu. Poniżej nich można dodać kolejne nagłówki.

Lista kontrolna tworzenia treści

Podczas pisania strony spełnij wymagania z obu list kontrolnych. Wewnętrzny standard definiuje każdy element normatywnie i wskazuje standard, na którym się opiera.

Przyjazność dla programistów:

• Pobieraj uruchamialne przykłady z examples/ lub tests/Cookbook i dodaj do każdego bloku kodu ciąg informacyjny title=.
• Podaj wymagania wstępne w front-matter oraz we wstępie.
• Pokaż oczekiwane wyjście dla każdego przykładu, który je generuje.
• Dbaj, aby bloki były gotowe do skopiowania i wklejenia: jeden język na blok, pełne nazwy przy pierwszym użyciu oraz brak końcowych znaków zachęty.
• Pokazuj kod bezpieczny domyślnie: przykłady produkcyjne używają try/catch z najbardziej szczegółowym wyjątkiem NextPDF i nigdy nie mają pustego bloku catch.
• Zakończ odnośnikami prowadzącymi dalej i ustaw w front-matter pole related:.

Gotowość do tłumaczenia:

• Wyrażaj jedną myśl w zdaniu, aby ograniczyć zakres tłumaczenia maszynowego.
• Utrzymuj nagłówki i etykiety krótkie, ponieważ tekst w większości języków docelowych się wydłuża.
• Unikaj idiomów.
• Umieszczaj nazwy symboli, klucze konfiguracji, flagi CLI i nazwy wyjątków w formatowaniu kodu; nazwy standardów, takie jak PDF/A-4, PAdES i eIDAS, nigdy nie są tłumaczone.
• Ustaw i18n_ready i xliff_segments zgodnie z prawdą i pisz w Unicode NFC.

W kwestii tonu, przykładów kodu, terminologii i stylu cytowania przestrzegaj zatwierdzonego arkusza nadpisań stylistycznych, do którego odsyła wewnętrzny standard.

Podłączanie bramek kontrolnych

Podłącz nową stronę zgodnie z tą uporządkowaną procedurą:

1. Utwórz szkielet strony tak, aby jej front-matter pasował do schematu witryny.
2. Napisz treść zgodnie z nagłówkami wymaganymi dla danego rodzaju strony.
3. Dodaj wpis { path, owner, kind, headings[] } do docs/manual-contract.json. Ścieżkę podaje się względem src/content/docs; należy zapisać ją z użyciem ukośników w przód, bez ukośnika na początku ani ...
4. W przypadku dokumentacji referencyjnej API dodaj symbole strony do docs/api-coverage-manifest.json; każdy symbol musi pojawić się na stronie i istnieć w źródle.
5. Zaktualizuj docs/source-manifest.json tylko wtedy, gdy strona pochodzi z nowego repozytorium źródłowego.
6. Dodaj stronę do właściwej grupy paska bocznego w astro.config.mjs jako jawny wpis.
7. Dodaj dla strony dostępnej tylko w języku angielskim wiersz pokrycia lokalizacji ze wszystkimi siedemnastoma komórkami lokalizacji ustawionymi na missing.
8. Uruchom bramki kontrolne dokumentacji, kompilację oraz sprawdzenie budżetu wydajności.

Strony należące do witryny znajdują się w src/content/docs, mają pole owner ustawione na nextpdf-docs i nigdy nie zawierają znacznika agregacji. Strony agregowane pochodzą z repozytorium źródłowego. Ich flaga publikacji znajduje się w front-matter źródła, więc edytuj ją tam, a nie tutaj.

Zobacz także

• Integracje: największy przykład rozbudowanej struktury podręcznika obejmującej wiele pakietów.
• Wewnętrzny dokument zarządczy docs/style/expansion-standard.md zawiera pełny kontrakt: dokładne listy nagłówków dla każdego rodzaju strony, reguły cytowania oraz kompletną procedurę podłączania bramek kontrolnych.