Cách viết tài liệu API chất lượng mà dễ hiểu

Tài liệu về API là lựa chọn hàng đầu khi bạn muốn học về cách sử dụng API, tùy vào chất lượng của tài liệu mà nó còn ảnh hưởng tới kinh nghiệm mà developer có được. Bởi nó miêu tả những khả năng của một giao diện lập trình ứng dụng và cách sử dụng chúng, do đó mà tài liệu hướng dẫn API của bạn cũng sẽ tạo nên hình ảnh cho sản phẩm của mình.

Trong bài viết này tôi sẽ chia sẻ những kinh nghiệm cá nhân về cách viết tài liệu hướng dẫn về API nhằm giúp các bạn có được những API chất lượng nhất có thể.

Biết rõ người đọc của bạn là ai

Biết rõ đối tượng sẽ đọc bài viết của bạn cũng như làm cách nào để nội dung dễ hiểu nhất cho họ sẽ giúp bạn đưa ra quyết định về cách thiết kế, trình bày cũng như văn phong. Bạn sẽ phải hiểu nhóm người đọc tài liều của bạn là ai và họ dùng nó cho mục đích gì.

DEVELOPERS

Do sự khác biệt về kĩ năng, kinh nghiệm và vai trò trong project khác nhau nên đây nhóm có sự đa dạng và lớn nhất.  Họ sẽ dùng tài liệu của bạn theo nhiều cách khác nhau.

Tại Pronovix, chúng tôi bắt đầu với developer portal workshops cùng client nhằm giúp họ hiểu thêm về nhu cầu của developer cũng như cách hỗ trợ họ – và điều mà họ muốn xem nhất trong tài liệu API.

Người mới

Developer thiếu kinh nghiệm với  API  thường sẽ cần nhiều sự giúp đỡ từ bạn hơn. Do đó mà họ sẽ rất tập trung và hứng thú với quickstart guide cũng như các bài tutorial từng bước một.

Developers có kinh nghiệm

Là những developer đã dùng API của bạn và họ sẽ thường xuyên dùng doc tài liệu của bạn để tham khảo. Họ sẽ chú ý vào các thông tin tóm tắt về tất cả các tính năng API có, vì thế việc trình bài gói gọn dễ đọc là rất cần thiết.

Debuggers

Developer sẽ gặp error trong quá trình sử dụng API của bạn sẽ dựa vào tài liệu tham khảo nhằm phân tích và xác định lỗi để khắc phục chúng.

Developer nội bộ:

Các công ty cung cấp API thường quá tập trung vào nhóm đối tượng bên ngoài mà quên mất rằng các developer của mình cũng cần phải xem tài liệu về API.

Decison  Maker

Bao gồm CTO và PM cũng sẽ kiểm tra và đọc qua tài liệu API của bạn nhằm đánh giá chất lượng và có phù hợp với project của họ hay không.

Nhóm người đọc khác

Mặc dù không nhiều nhưng nhà báo, marketer và thậm chí là đối thủ của bạn cũng sẽ đọc tài liệu API.

Mục đích của bạn khi viết tài liệu về API là gì?

Mọi thứ trong tài liệu API của bạn đều phải dựa trên nền tảng rằng nó giải thích rõ ràng mọi call và parameter.

Ít nhất thì bạn cũng phải miêu tả được:

• Tính năng của từng call trong API của bạn
• Từng parameter  và giá trị của chúng cũng như types, formatting, rules, chúng có bắt buộc hay không.

Trình bày theo nhiều phần khác nhau

Người đọc sẽ không xem tài liệu về API của bạn theo thứ tự đâu mà họ sẽ chọn những phần mà họ thấy cần hoặc thú vị. Do đó mà bạn sẽ phải bảo đảm mọi phần trong tài liệu đều phải đầy đủ và rõ ràng.

Ví dụ

Để có thể áp dụng API của bạn, developer cần phải hiểu rõ về nó kèm theo domain mà nó được dùng vào. Nhờ vào các ví dụ mà sẽ tiết kiệm được thời gian cho người dùng để làm quen với sản phẩm của bạn.

Hãy thêm vào những thứ sau đây vào dưới phần miêu tả call của bạn:

• Một ví dụ làm thế nào mà call đó được thực hiện
• Giải thích về request
• Ví dụ về responses

Theo nhiều nghiên cứu, một số developer sẽ thử vào code luôn khi họ học về một API mới. Do đó các ví dụ sẽ giúp họ tiếp thu rất nhanh.

Error messages

Trong quá trình phát triển sẽ luôn có sai sót, việc sửa chúng mà không nhờ tới các tài liệu thật sự rất khó khăn và tốn nhiều thời gian. Để giúp cho việc này dễ dàng nhất có thể, error message nên giúp developer hiểu được:

• Vấn đề mắc phải là gì
• Liệu lỗi bắt nguồn từ code của họ hay là từ API được dùng
• Và cách sửa vấn đề đó

Hướng dẫn bắt đầu nhanh

Người dùng mới cũng như các developer thiếu kinh nghiệm sẽ gặp nhiều khó khăn khi sử dụng API của bạn:

• Mọi thứ đều mới lạ nên sẽ khó học
• Không quen thuộc với cấu trúc, domain của API bạn
• Không biết nên bắt đầu từ đâu

Nếu bạn không làm cho quá trình học dễ dàng hơn thì người dùng sẽ không bao giờ muốn bỏ công để học dùng API của bạn.

Rất nhiều  developer ưa chuộng quickstart guide bởi nó giúp họ học rất nhanh. Bài hướng dẫn nên được giản đơn hết mức có thể, đảm bảo cho người mới đọc hiểu. Thường quickstart guide bao gồm những thông tin về domain cũng như giới thiệu về expression và phương pháp liên quan tới domain. Những người đọc quickstart guide cũng được xem như là hoàn toàn không biết gì về API của bạn.

Tutorials

Là những bài hướng dẫn chi tiết từng bước một và thường là về một tính năng cụ thể mà developer có thể áp dụng với API của bạn.

Nội dung và văn phong của những bài hướng dẫn này nên thực tiễn và đầy chi tiết rõ ràng. Mỗi bước sẽ có đầy đủ thông tin cho bước đó, không thêm không bớt. Nhờ đó mà người đọc sẽ dễ tập trung tiếp thu mà không lo bị quá tải.

Các phần miêu tả cần chi tiết và thật đơn giản để giúp người đọc hiểu rõ. Đặc biệt nếu những bài hướng dẫn về topic và nội dung khá dài cũng như quá phức tạp thì hãy chia nó thành nhiều phần nhỏ hơn để bảo đảm người dùng vẫn có thể tiếp thu nhẹ nhàng.

Các chủ đề chung

Khi áp dụng API của bạn, sẽ có những chủ đề khá là rộng mà người dùng cần phải biết như:

Tính xác thực: Được thực hiện theo nhiều cách khác nhau tùy vào API. authentication là một chủ đề khá khó nên bạn sẽ cần giải thích rất chi tiết nhiều phần quan trọng như: làm sao để lấy dc chứng nhận rồi cách pass chúng qua server cũng như cách thức mà API thực hiện.

Cách xử lí lỗi: Hiện giờ vẫn chưa có một chuẩn mực sửa lỗi nào cả nên bạn cần phải giúp developer bằng cách gửi cho họ thông tin về lỗi, nguyên nhân và cách sửa chúng.

HTTP request: Bạn có thể sẽ viết thêm tài liệu có liên quan tới HTTP bao gồm types, status codes, và caching.

Layout và navigation

Layout và navigation đóng vai trò then chốt trong trải nghiệm của user. Cho dù không có phương pháp chung cho mọi API doc, ta vẫn có một số cách thức khá hiệu quả giúp người dùng có thể tương tác tốt hơn.

DYNAMIC LAYOUT

Giúp việc navigation dễ dàng hơn cho người dùng khi muốn tìm hiểu về một chủ đề nhất định trong API. Ngoài ra nó còn tiện lợi cho bạn khi muốn mở rộng tài liệu của mình về sau.

Thiết kế theo phong cách 1 trang

Nếu tài liệu về API của bạn không nhiều thì hãy theo cách thiết kế 1 trang để user có thấy được toàn bộ các mục lục ngay từ cái nhìn đầu tiên. Ngoài ra nó còn giúp người đọc dùng tính năng tìm kiếm của trình duyệt.

Luôn hiển thị NAVIGATION

Hãy luôn giữa thanh navigation bar luôn hiển thị cho người dùng.

LAYOUT nhiều cột

Với Layout 2 tới 3 cột với navigation bên trái cùng thông tin và ví dụ bên phải, việc đọc hiểu sẽ dễ dàng hơn.

SYNTAX được HIGHLIGHT

Giúp các ví dụ dễ đọc hơn với những cú pháp được high light

Edit

Mọi bài viết của bạn nên được qua quá trình edit trước khi đăng. Đây là chuyện bình thường đối với báo chí nhưng lại ít được để tâm tới với tài liệu về công nghệ.

Người viết API doc cần phải kiểm tra một cách kĩ lưỡng nhằm bảo đảm tính xác thực và đầy đủ về mặt nội dung. Đồng thời bài viết phải được trình bài theo thứ tự rõ ràng, logic mà không bị dư thừa.

Editor là người sẽ đọc và kiểm tra lỗi chính tả, ngữ pháp cũng như những phần có thể bị khó hiểu cho người đọc.

Mặc dù đây là quá trình khá  mệt nhọc nhưng nó sẽ ảnh hưởng rất lớn đến trải nghiệm của người dùng cũng như hình ảnh cho sản phẩm của bạn.

Luôn cập nhật liên tục

Không có gì tệ hơn khi nội dung của tài liệu API bị lỗi thời, người dùng sẽ trở nên vô cùng khốn đốn khi gặp phải những tính năng đã bị xóa bỏ hay những tính năng mới mà lại không hề có thông tin rõ ràng về nó. Kết quả là tính trung thực và chính xác của tài liệu sẽ bị giảm đi rất nhiều.

Khi quản lí lượng tài liệu API, bạn nên chú ý những điều sau:

Các tính năng bị bỏ. Hãy ngay lập tức xóa những tài liệu về chúng bởi không còn cần thiết nữa và sẽ khiến user phí phạm thời gian cũng như công sức tìm hiểu.

Những tính năng mới. Hãy cố gắng chuẩn bị tài liệu về chúng thật sớm, từ trước cả khi launch.

Feedback. Luôn là nguồn thông tin tuyệt vời để bạn biết được mình cần cải thiện ở đâu cũng như hiểu rõ hơn về mong muốn của như tính cách của người dùng.

Để thực hiện tất cả những điều trên thì bạn sẽ cần một hệ thống rõ ràng cho việc quản lí và bảo trì tài liệu của mình. Nhờ đó mà chất lượng của tài liệu API sẽ luôn được nâng cao và cải thiện.

Techtalk via alistapart