Cấu trúc tài liệu NextPDF

Tổng quan nhanh

Sổ tay NextPDF tuân theo một bộ quy ước ổn định. Mỗi trang có một chủ đề, một chế độ Diataxis và một loại trang. Mỗi loại trang có một bộ tiêu đề cấp 2 bắt buộc. Một nhóm nhỏ các tệp manifest và cổng kiểm tra giúp cấu trúc luôn nhất quán khi sổ tay mở rộng.

Trang này phác thảo hệ thống đó để bạn có thể đặt phần đóng góp của mình đúng vị trí. Toàn bộ quy ước chuẩn tắc, bao gồm danh sách tiêu đề chính xác, quy tắc trích dẫn và quy trình kết nối cổng, nằm trong tài liệu quản trị nội bộ docs/style/expansion-standard.md. Hãy đọc trang này trước. Khi biên soạn, hãy tham khảo tài liệu đó.

Chọn loại trang

Áp dụng các quy tắc này theo thứ tự để quyết định nên thêm trang mới hay mở rộng trang hiện có:

1. Nếu nội dung là một chủ đề riêng biệt mà người đọc không mong đợi gặp trên trang hiện có, hãy thêm một trang mới.
2. Nếu nội dung hoàn thiện một chủ đề mà trang hiện có đã phụ trách, hãy mở rộng trang đó.
3. Nếu nội dung là chi tiết chuyên sâu khiến một trang cài đặt, hướng dẫn nhanh hoặc trang tác vụ trở nên quá dài, hãy chuyển nội dung đó sang một trang riêng và liên kết đến trang đó.
4. Nếu không, hãy mở rộng trang hiện có.

Sau khi xác định trang nên tồn tại, hãy đặt chế độ Diataxis cho trang. Chế độ này quyết định loại trang:

• Hướng dẫn từng bước dành cho người mới học. Hãy dùng một hướng dẫn tác vụ viết theo dạng công thức.
• Hướng dẫn thao tác giúp người đọc đã có kỹ năng hoàn thành một tác vụ. Hãy dùng một hướng dẫn tác vụ, một hướng dẫn API máy chủ hoặc một hướng dẫn bộ công cụ phát triển phần mềm.
• Tài liệu tham khảo trình bày các dữ kiện chính xác. Hãy dùng một tài liệu tham khảo API hoặc một trang mục lục.
• Phần giải thích giúp người đọc xây dựng hiểu biết. Hãy dùng một hướng dẫn dành cho nhà phát triển hoặc một hướng dẫn tính năng cao cấp.

Ngôn ngữ giản dị là chuẩn cơ bản cho mọi chế độ, không phải một chế độ riêng.

Danh mục loại trang

Quy ước của sổ tay công nhận các loại sau. Hãy tái sử dụng một loại có sẵn bất cứ khi nào trang của bạn có bảng API. Chỉ tạo loại chỉ-có-nhãn mới cho trang không có bảng API.

• Các loại mục lục: section-index, api-index, extension-index.
• Loại tham khảo: api-reference. Hãy tái sử dụng loại này cho mọi trang có bảng API chuẩn, kể cả tài liệu tham khảo của máy chủ và Python SDK.
• Loại giải thích: developer-guide. Hãy tái sử dụng loại này cho nội dung về kiến trúc, vòng đời và điểm mở rộng, kể cả hướng dẫn của máy chủ và Python SDK.
• Các loại chỉ-có-nhãn mới: premium-feature-guide và task-guide, cả hai đều dành cho trang không có bảng API.

Mọi trang đều mở đầu bằng ## At a glance. Mọi trang api-reference đều có bảng API dùng chung và tiêu đề Development notes. Các tiêu đề bắt buộc là tiêu đề cấp 2, mỗi tiêu đề nằm trên một dòng riêng. Bạn có thể thêm các tiêu đề khác bên dưới những tiêu đề này.

Danh sách kiểm tra khi biên soạn

Khi viết một trang, bạn phải đáp ứng cả hai danh sách kiểm tra. Tiêu chuẩn nội bộ nêu từng mục theo cách chuẩn tắc và liên kết đến tiêu chuẩn hỗ trợ tương ứng.

Mức độ thân thiện với nhà phát triển:

• Hãy lấy các ví dụ có thể chạy được từ examples/ hoặc tests/Cookbook, và gắn cho mỗi khối mã được rào một chuỗi thông tin title=.
• Hãy nêu các điều kiện tiên quyết trong front-matter và trong phần mở đầu.
• Hãy hiển thị kết quả mong đợi cho bất kỳ mẫu nào tạo ra kết quả.
• Hãy giữ các khối mã luôn sẵn sàng để sao chép và dán: mỗi khối một ngôn ngữ, dùng tên đầy đủ ở lần xuất hiện đầu tiên và không có ký tự dấu nhắc ở cuối.
• Hãy trình bày mã an toàn theo mặc định: các mẫu dùng cho sản xuất sử dụng try/catch với ngoại lệ NextPDF cụ thể nhất và không bao giờ để khối catch rỗng.
• Hãy kết thúc bằng các liên kết dẫn tiếp và đặt related: trong front-matter.

Mức độ sẵn sàng để dịch:

• Hãy viết mỗi câu một ý để bản dịch máy luôn nằm trong giới hạn.
• Hãy giữ tiêu đề và nhãn ngắn gọn vì hầu hết ngôn ngữ đích sẽ dài hơn sau khi dịch.
• Tránh dùng thành ngữ.
• Hãy giữ tên ký hiệu, khóa cấu hình, cờ CLI và tên ngoại lệ ở định dạng mã; các tên tiêu chuẩn như PDF/A-4, PAdES và eIDAS không bao giờ được dịch.
• Hãy đặt i18n_ready và xliff_segments một cách trung thực, và viết theo chuẩn Unicode NFC.

Về giọng văn, mẫu mã, thuật ngữ và cách trích dẫn, hãy tuân theo bảng ghi đè phong cách đã được phê chuẩn mà tiêu chuẩn nội bộ tham chiếu.

Kết nối cổng kiểm tra

Hãy kết nối một trang mới theo quy trình tuần tự sau:

1. Tạo khung trang sao cho front-matter của trang khớp với lược đồ của trang web.
2. Biên soạn phần nội dung theo các tiêu đề bắt buộc của loại trang.
3. Thêm một mục { path, owner, kind, headings[] } vào docs/manual-contract.json. Đường dẫn là tương đối so với src/content/docs, dùng dấu gạch chéo xuôi, không có dấu gạch chéo ở đầu và không có ...
4. Đối với một tài liệu tham khảo API, hãy thêm các ký hiệu của trang vào docs/api-coverage-manifest.json; mỗi ký hiệu phải xuất hiện trong trang và tồn tại trong mã nguồn.
5. Chỉ cập nhật docs/source-manifest.json khi trang đến từ một kho mã nguồn mới.
6. Thêm trang vào đúng nhóm thanh bên trong astro.config.mjs dưới dạng một mục tường minh.
7. Thêm một hàng phạm vi ngôn ngữ với cả mười bảy ô ngôn ngữ đều đặt là missing cho một trang chỉ có tiếng Anh.
8. Chạy các cổng kiểm tra tài liệu, quá trình dựng và ngân sách hiệu năng.

Các trang do trang web sở hữu nằm trong src/content/docs, đặt owner thành nextpdf-docs, và không bao giờ mang dấu hiệu tổng hợp. Các trang được tổng hợp đến từ một kho mã nguồn. Cờ xuất bản của chúng nằm trong front-matter ở nguồn, vì vậy hãy chỉnh sửa chúng tại đó chứ không phải tại đây.

Xem thêm

• Tích hợp: ví dụ minh họa lớn nhất về cấu trúc sổ tay trải rộng trên nhiều gói.
• Tài liệu quản trị nội bộ docs/style/expansion-standard.md chứa toàn bộ quy ước: danh sách tiêu đề chính xác cho mọi loại trang, quy tắc trích dẫn và quy trình kết nối cổng đầy đủ.