Mục lục

Loại tài liệu

Dưới đây là danh sách sơ lược các loại tài liệu được chấp nhận trên amp.dev:

Thực hành giới thiệu

Thực hành giới thiệu giúp nhà phát triển nắm bắt được khái niệm chung về công nghệ. Nó giúp họ bắt đầu lập trình và kết thúc với một dự án "Hello World" cơ bản hoàn chỉnh. Các bài thực hành giới thiệu cho thấy cách bạn có thể xây dựng một tính năng thiết yếu của AMP trong một bài hướng dẫn từng bước chi tiết. Hãy kết hợp bài Thực hành giới thiệu với các code mẫu inline và/hoặc code có thể tải về và điều chỉnh chút ít trước khi thực thi.

Các ví dụ của amp.dev:

Nên	Không nên
Cung cấp hướng dẫn với những lời giải thích ngắn gọn và số bước thực hiện tối thiểu.	Phân tích quá sâu vào các tính năng của dự án. Có thể có nhiều cách để hoàn thành bài thực hành, nhưng mục đích không phải là chỉ ra tất cả các cách đó, mà là một phương pháp tốt, khả dĩ.
Cung cấp một môi trường đơn giản cùng các công cụ để thiết lập.	Nghĩ rằng nhà phát triển đã quen với sản phẩm và có khả năng lập trình chuyên nghiệp.
Đảm bảo code mẫu đơn giản về mặt hình thức.	Quá phức tạp, kiểu cách, trừ khi trọng tâm của bài thực hành là về phong cách.
Cung cấp ảnh chụp màn hình cho mỗi bước cùng bản demo hoàn chỉnh.	Chỉ cung cấp code mẫu.
Tạo một lời kêu gọi hành động. Định hướng việc nên làm tiếp theo cho nhà phát triển.	Giải thích bổ sung dài dòng về ví dụ. Hãy cân nhắc việc mở một vấn đề để hướng dẫn hoặc thực hành nếu bạn cảm thấy nó vẫn chưa đủ.

Thực hành nâng cao

Bài thực hành nâng cao giúp các nhà phát triển hoàn thành một công việc cụ thể. Chúng giả sử rằng nhà phát triển đã quen với AMP. Các bài thực hành này nên hướng dẫn cách xây dựng một trải nghiệm, tích hợp một tính năng hoặc hoàn thành các tác vụ triển khai.

Các ví dụ của amp.dev:

Nên	Không nên
Cung cấp hướng dẫn từng bước với một dự án đầu cuối rõ ràng.	Nói quá chi tiết với những khái niệm quá phức tạp.
Cung cấp code mẫu hoặc code cơ bản có thể được tải về. Ngoài ra, cho phép tải về dự án hoàn chỉnh.	Cung cấp các ví dụ thay thế hoặc quy trình để đạt được kết quả cuối cùng.
Tạo một môi trường cắm và thực thi.	Liên kết ra một bài thực hành thiết lập ở bên ngoài. Các bài thực hành nên gói gọn trong khuôn khổ của nó.

Hướng dẫn giới thiệu

Một hướng dẫn giới thiệu cung cấp một cái nhìn tổng quan về những thông tin liên quan để bắt đầu với AMP. Bài hướng dẫn này cần xác định rõ tính năng cùng mô tả của tính năng đó, và kết thúc bằng ứng dụng của nó. Hướng dẫn giới thiệu giúp nhà phát triển hiểu các yêu cầu cơ bản của tính năng mà không hướng dẫn họ cách triển khai nó. Nếu bạn đang mô tả từng bước một quy trình với code mẫu, thì có thể bạn đang viết một bài thực hành. Nếu bạn đang phác họa tất cả các yếu tố lập trình cho một thành phần AMP, thì có thể bạn đang viết một tài liệu tham khảo.

Các ví dụ của amp.dev:

Nên	Không nên
Xác định rõ những nội dung của tài liệu.	Phân tích thành một quy trình chi tiết từng bước.
Giới thiệu về các tính năng và khái niệm. Liên kết đến tài liệu tham khảo cho những thông tin sử dụng nâng cao.	Mô tả rõ chi tiết.
Cung cấp code mẫu và ví dụ đời thực.	Tạo một ứng dụng hoàn chỉnh. Thay vào đó, hãy liên kết đến các ví dụ hoặc demo để giải thích thêm.
Liệt kê các ứng dụng kỹ thuật và hạn chế.	Liệt kê mọi ứng dụng kỹ thuật và cách thực hiện.

Hướng dẫn khái niệm

Hướng dẫn khái niệm giúp các nhà phát triển hiểu sâu hơn về AMP. Một hướng dẫn khái niệm cũng như một bản đồ địa hình. Nó thể hiện các con đường mòn khác nhau trong khu vực với chi tiết như thay đổi độ cao, nhưng không nêu rõ một lộ trình cụ thể qua địa hình này. Hướng dẫn khái niệm giải thích rõ về một tính năng và cách thức hoạt động của nó, chứ không phải làm thế nào để xây dựng tính năng đó.

Các ví dụ của amp.dev:

Nên	Không nên
Cung cấp cho nhà phát triển mọi yếu tố cần thiết để xây dựng một giải pháp.	Chủ động hướng dẫn nhà phát triển đến một trạng thái đầu cuối cụ thể.
Bao quát mọi khía cạnh của chủ đề.	Tập trung vào một tác vụ cụ thể.
Bao gồm hỗ trợ hình ảnh, ví dụ như sơ đồ hoặc ảnh chụp màn hình.	Suy nghĩ quá nhiều, bạn có thể yêu cầu hỗ trợ hình ảnh từ [nhóm làm việc mở rộng](https://github.com/ampproject/wg-outreach).
Cung cấp code mẫu và liên kết đến các hướng dẫn khác.	Cung cấp bản tải về cho dự án hoàn chỉnh hoặc đi ra ngoài chủ đề.

Tài liệu tham khảo

Tài liệu tham khảo liệt kê tất cả các yếu tố lập trình cho một thành phần AMP. Nó cung cấp thông tin hành vi chi tiết và được thiết kế để đọc lướt. Tài liệu tham khảo nên bao gồm code mẫu và minh họa các trường hợp sử dụng.

Tài liệu tham khảo của amp.dev có thể được tìm thấy trong danh mục thành phần AMP.

Tài liệu tham khảo AMP được đóng góp vào kho lưu trữ AMPHTML.

Nên	Không nên
Sử dụng ngôn ngữ rõ ràng và súc tích để giải thích rõ cách hoạt động của thành phần.	Giải thích một quy trình hay xây dựng một dự án.
Có cấu trúc thuận lợi cho việc đọc lướt tiêu đề, đầu mục và tiểu mục.	Ghép nhóm nội dung theo các tên trừu tượng.
Cung cấp trích đoạn code để thể hiện cách sử dụng thành phần.	Tạo các ứng dụng demo hoàn chỉnh.

Written by @CrystalOnScript