Bạn đang tìm cách hợp lý hóa quy trình tài liệu sản phẩm mà không yêu cầu chuyên môn kỹ thuật? Apidog cung cấp một giải pháp toàn diện giúp các nhà quản lý sản phẩm và đội ngũ vận hành cộng tác liền mạch trong việc tạo, quản lý và xuất bản tài liệu chuyên nghiệp. Với giao diện trực quan, các tính năng cộng tác theo thời gian thực và khả năng xuất bản không cần bảo trì, Apidog thay đổi cách các đội ngũ tiếp cận quy trình làm việc tài liệu.
Mỗi sản phẩm đều cần có tài liệu riêng. Ngay cả khi sản phẩm của bạn là một ứng dụng hướng đến người tiêu dùng với thiết kế tương tác rất trực quan và đơn giản, vẫn sẽ có những khu vực cần giải thích thêm, nhưng sẽ làm tăng độ phức tạp nếu được trình bày trực tiếp trong giao diện sản phẩm. Do đó, việc quản lý, bảo trì và xuất bản tài liệu là những mối quan tâm quan trọng đối với mọi sản phẩm.
Khi xây dựng tài liệu sản phẩm, các đội ngũ thường sử dụng các công cụ tài liệu có sẵn như Notion, hoặc các công cụ quản lý nội dung như Confluence và CMS, hoặc các công cụ tạo tài liệu như Docusaurus và Gitbook. Tuy nhiên, những giải pháp này thường gặp phải các vấn đề sau:
- Tài liệu yêu cầu viết mã để tạo, với chi phí cao. Ngay cả sau khi tài liệu được viết, trải nghiệm đọc thực tế thường không đạt được kỳ vọng;
- Tài liệu liên quan đến nhiều vai trò cộng tác, gây khó khăn trong việc quản lý phiên bản và khó truyền đạt các đề xuất tối ưu hóa cho người khác;
- Việc xuất bản tài liệu hoàn chỉnh lên môi trường sản xuất hoặc quá đơn giản hoặc quá phức tạp, có thể liên quan đến các quy trình kỹ thuật mà đồng nghiệp không chuyên về kỹ thuật khó xử lý, dẫn đến lỗi.
Đội ngũ Apidog trước đây đã sử dụng Docusaurus để tạo tài liệu của chúng tôi. Khi tài liệu của chúng tôi tiếp tục được lặp lại, chúng tôi cũng gặp phải một số vấn đề đã nêu ở trên. Sau khi tổng hợp kinh nghiệm và bài học rút ra, chúng tôi đã phát triển các giải pháp và tích hợp chúng vào Apidog. Giờ đây, tài liệu sản phẩm của đội ngũ Apidog đã được di chuyển hoàn toàn sang Apidog, với tất cả việc tạo và trình bày đều do Apidog xử lý.
Tôi sẽ chia sẻ cách chúng tôi xây dựng tài liệu sản phẩm thông qua Apidog. Trước đó, nếu bạn muốn xem xét kỹ hơn các hiệu ứng cụ thể của tài liệu sản phẩm của Apidog, bạn có thể kiểm tra tài liệu trợ giúp của Apidog - phản hồi của bạn luôn được chào đón.
Bối cảnh
Trước khi giới thiệu cách làm của chúng tôi, có một số bối cảnh có thể cần được giải thích trước, để mọi người có thể hiểu rõ hơn lý do tại sao chúng tôi làm theo cách này. Tài liệu sản phẩm của công ty chúng tôi thường được tạo ra thông qua sự cộng tác giữa các đồng nghiệp từ bộ phận sản phẩm và vận hành. Quy trình chính như sau:
Quy trình trên không yêu cầu sự tham gia của nhân viên kỹ thuật - tất cả các hoạt động liên quan đến tài liệu sản phẩm đều được hoàn thành bởi các đồng nghiệp từ hai bộ phận này. Tiếp theo, tôi sẽ giải thích cách hoàn thành việc xây dựng tài liệu sản phẩm thông qua Apidog theo quy trình này.
Quy trình cốt lõi
1. Tạo nhánh Sprint để quản lý và cộng tác nội dung
Sau khi một vòng lặp phát triển bắt đầu, các đồng nghiệp vận hành sẽ tạo một nhánh lặp trong Apidog để đặt tất cả các tài liệu liên quan đến thay đổi trong vòng lặp hiện tại vào nhánh này để cộng tác, tránh tác động trực tiếp đến nhánh chính.
Sau khi tạo, các nhà quản lý sản phẩm nhập các tài liệu hiện có cần sửa đổi vào nhánh lặp này dựa trên các tính năng thực tế được cập nhật trong vòng lặp, và tạo tài liệu mới cho các tính năng mới trực tiếp trong nhánh lặp. Thao tác ở đây hoàn toàn nhất quán với việc sử dụng các nhánh lặp cho tài liệu API.
Vì chúng tôi đã thiết lập bảo vệ trên nhánh chính, nên không cho phép thay đổi trực tiếp nội dung tài liệu trong nhánh chính. Điều này có nghĩa là bạn không thể sửa đổi thủ công nội dung trong tài liệu đã xuất bản mà người dùng có thể thấy trực tiếp, giúp tài liệu sản phẩm ổn định hơn và giảm các trường hợp thay đổi ngẫu nhiên dẫn đến nội dung không chính xác hiển thị cho người dùng.
2. Sử dụng Trình chỉnh sửa Markdown đẹp mắt để viết từng tài liệu
Các nhà quản lý sản phẩm sẽ sử dụng Markdown để viết tài liệu cần được cập nhật trong vòng lặp hiện tại trong nhánh lặp. Chức năng Markdown của Apidog rất mạnh mẽ, với nhiều thành phần trực quan có thể nhấp để chèn nhiều kiểu phức tạp với rào cản thấp, cho phép bạn dễ dàng viết các bài viết đẹp mắt mà không tốn thêm công sức.
Ngoài việc chèn trực quan theo phong cách MD thông thường, Apidog đã thêm các tính năng đặc biệt sau:
- Chèn API/tài liệu dự án, cho phép các tài liệu liên kết với nhau tạo thành chuỗi tham chiếu với điều hướng liền mạch, mang lại cho người đọc trải nghiệm mượt mà hơn và giải quyết tốt hơn nhu cầu và vấn đề của người đọc - đây là một tính năng rất quan trọng.
- Cung cấp các chức năng chèn tài nguyên phong phú, như Biểu tượng (Icons), khối nổi bật (highlight blocks), bảng (tables), bước (steps), Mermaid, video, v.v., để bạn không phải tốn thời gian tự tìm tài nguyên hoặc học cú pháp kiểu MD để làm cho tài liệu trông đẹp hơn.
3. Đồng nghiệp Sản phẩm/Vận hành cộng tác để hoàn thiện tài liệu
Sau khi các nhà quản lý sản phẩm viết phiên bản ban đầu của tài liệu trong nhánh lặp, để cải thiện chất lượng, sự rõ ràng và tính hữu ích cho người dùng của tài liệu, họ chuyển giao tài liệu cho các đồng nghiệp vận hành để đọc từ góc độ người dùng và đưa ra các đề xuất sửa đổi để hoàn thiện.
Đây từng là phần tốn thời gian và công sức nhất, đòi hỏi sự cộng tác lẫn nhau giữa hai bên, với một bên giải thích ý tưởng của mình và đưa ra các đề xuất sửa đổi cụ thể cho một số phần; sau đó bên kia tiếp nhận, hiểu và thực hiện các thay đổi. Trong quá trình qua lại, thường có nhiều vấn đề khác nhau như hiểu lầm, thay đổi không chính xác và sự khác biệt về nội dung giữa các phiên bản tài liệu, dẫn đến hiệu quả rất thấp.
Giờ đây, khi sử dụng Apidog, cả hai bên có thể trực tiếp thực hiện sửa đổi trong tài liệu, với thông báo tin nhắn theo thời gian thực được đẩy đến IM khi có thay đổi, cho phép người khác ngay lập tức truy cập tài liệu và dễ dàng xem các thay đổi cụ thể, cải thiện đáng kể hiệu quả cộng tác. Dưới đây là các bước cụ thể:
- Các nhà quản lý sản phẩm tạo phiên bản ban đầu của tài liệu. Sau khi nhân viên vận hành thấy thông báo, họ đọc tài liệu và trực tiếp thực hiện sửa đổi đối với nội dung họ muốn thay đổi trong tài liệu này.
- Các sửa đổi tự động kích hoạt thông báo khi lưu, gửi thẻ tin nhắn thay đổi đến nhóm IM đã được cấu hình sẵn. Sau khi các thành viên nhóm xem thẻ tin nhắn tổng quan về thay đổi, họ có thể nhấp vào liên kết thông báo để truy cập tài liệu liên quan chỉ bằng một cú nhấp chuột.
- Thông qua lịch sử sửa đổi, so sánh sự khác biệt bằng cách chọn phiên bản hiện tại và phiên bản gốc để dễ dàng xem các sửa đổi của bên kia và quyết định cách điều chỉnh tài liệu. Bạn có thể chọn không chấp nhận đề xuất và khôi phục về phiên bản gốc, hoặc chấp nhận sửa đổi và giữ phiên bản mới nhất.
Các đội ngũ sản phẩm và vận hành lặp lại các bước trên cho đến khi nội dung tài liệu được hoàn thiện và một phiên bản được mọi người chấp thuận được xác định.
4. Chuẩn bị và xem xét trước khi xuất bản tài liệu chính thức
Để đảm bảo nội dung và ảnh chụp màn hình sản phẩm trong tài liệu hoàn toàn nhất quán với những gì người dùng có thể truy cập, chúng tôi khuyên bạn nên chụp ảnh màn hình trên môi trường sản xuất của sản phẩm. Điều này cũng cho phép xác minh rằng các khả năng mới được ra mắt trong môi trường sản xuất đang hoạt động bình thường. Sau khi nhân viên vận hành sử dụng các tính năng mới trực tuyến và chụp ảnh màn hình, họ sẽ thêm chúng vào các bài viết.
Bộ phận vận hành xác nhận các tài liệu nội dung đã hoàn thành từ vòng lặp này, chọn chúng và gửi yêu cầu MR để hợp nhất vào nhánh chính.
Quản lý vận hành hoặc các quản trị viên dự án khác xem xét nội dung tài liệu sẽ được xuất bản, xác nhận rằng nó chính xác, và sau đó chọn hợp nhất vào nhánh chính.
Sau khi việc hợp nhất hoàn tất, khi người dùng truy cập các tài liệu đã xuất bản, họ có thể thấy nội dung mới nhất đã được hợp nhất vào nhánh chính.
Các ưu điểm khác
Ngoài các khả năng đã được giới thiệu, Apidog còn có các tính năng sau về việc xuất bản tài liệu để giúp mọi người xây dựng các trang tài liệu sản phẩm đáp ứng tốt hơn nhu cầu của họ.
1. Đặt kiểu dáng tổng thể của trang tài liệu phù hợp với phong cách sản phẩm/công ty
Bạn có thể đặt kiểu dáng tổng thể của trang tài liệu đã xuất bản, làm cho phong cách toàn bộ trang web phù hợp hơn với tông màu của công ty bạn, và thêm nhiều tài nguyên liên quan cùng các liên kết nội dung công ty để mang lại trải nghiệm tốt hơn cho người dùng.
Tài liệu trợ giúp của Apidog đã đặt logo riêng và một số liên kết tài nguyên liên quan đến Apidog. Phía trên bên trái chứa logo công ty, phía trên bên phải chứa nhiều liên kết tài nguyên liên quan đến công ty, và tài liệu API mở mà các nhà phát triển quan tâm hơn cũng được đặt trong tài liệu sản phẩm:
2. Trải nghiệm xuất bản không cần bảo trì
Trong Apidog, bạn chỉ cần nhấp vào nút "Xuất bản" trong tính năng xuất bản tài liệu để xuất bản toàn bộ tài liệu lên internet chỉ bằng một cú nhấp chuột để người dùng của bạn đọc. Apidog chính thức cung cấp các tên miền để mọi người sử dụng, tiết kiệm rất nhiều công việc bảo trì.
Tất nhiên, nếu bạn cần làm cho tài liệu trông giống trang web của công ty mình hơn, chúng tôi cũng cung cấp chức năng tên miền tùy chỉnh, cho phép bạn sử dụng tên miền của công ty mình để truy cập tài liệu.
Bạn cũng có thể dễ dàng thiết lập tìm kiếm thông thường, tìm kiếm toàn văn bản Algolia, tích hợp GA, đặt chuyển hướng và các khả năng nâng cao khác trong các trang tài liệu sản phẩm đã xuất bản chỉ với các thao tác đơn giản. Các cấu hình này không yêu cầu người vận hành phải có đủ khả năng kỹ thuật - chúng có thể dễ dàng được thiết lập bằng cách làm theo hướng dẫn giao diện và tài liệu trợ giúp.
3. Nhiều cài đặt thân thiện với SEO
Apidog tự động tạo các Slug hợp lý cho các trang tài liệu đã xuất bản dựa trên các cài đặt cơ bản để người dùng có thể truy cập và chia sẻ chúng tốt hơn.
Tất nhiên, nếu bạn có nhu cầu SEO nâng cao hơn, nó cũng hỗ trợ Slug tùy chỉnh, Meta Data và nhiều cài đặt nội dung khác cho từng tài liệu riêng lẻ.
Kết luận
Trên đây là cách thực hành cụ thể việc sử dụng Apidog để bảo trì tài liệu sản phẩm.
Ngoài những nội dung đã đề cập ở trên, chúng tôi cũng có thể duy trì tài liệu trợ giúp sản phẩm, tài liệu dành cho nhà phát triển và tài liệu API theo một phong cách thống nhất và liên kết tất cả chúng lại với nhau, mang lại trải nghiệm người dùng tốt hơn nữa. Nếu tình hình thực tế của bạn phù hợp, rất hoan nghênh bạn thử nghiệm cách làm này và giới thiệu nó cho các đồng nghiệp khác. Chúng tôi hy vọng điều này có thể mang lại một số cải thiện về hiệu quả và chất lượng cho công việc xây dựng tài liệu sản phẩm của bạn.