Product User Guide
Các vấn đề liên quan đến tài liệu hướng dẫn sử dụng sản phẩm. Kỹ thuật, hướng dẫn viết bài, build và publish lên web.
Giới thiệu chung
Mỗi sản phẩm, khi đưa ra thị trường để giảm thiểu chi phí đào tạo, hỗ trợ cần xây dựng hệ thống tài liệu, video hướng dẫn sử dụng thật đầy đủ, chi tiết.
Tài liệu hướng dẫn sử dụng của sản phẩm được phân thành cách loại:
Hướng dẫn sử dụng
Mô tả cách thực hiện từng chức năng trong hệ thống
- HDSD thường được viết theo từng phân hệ, trong mỗi phân hệ có tính năng, mỗi tính năng sẽ có nhiều chức năng bên trong.
Hướng dẫn tác nghiệp
Hướng dẫn sử dụng nhiều tính năng để hoàn thành một nghiệp vụ nào đó, giải quyết 1 công việc mà người dùng làm hàng ngày
- Ví dụ để thu tiền hàng thì cần dùng chức năng nào?
- Nghiệp vụ Hoàn ứng thì dùng tính năng nào?
- Thực hiện kết chuyển cuối kỳ thì cần sử dụng những chức năng nào?
Video
Hướng dẫn sử dụng tồn tại dướng dạng video quay màn hình thực hiện chức năng nào đó của hệ thống
Nền tảng kỹ thuật
MkDocs
Giới thiệu về MkDocs
- Xem một số shortcode tại đây: https://squidfunk.github.io/mkdocs-material/reference/abbreviations/
Sphinx
Xem thêm tài liệu của Sphinx
Trong bài này chỉ notes một số lưu ý của Sphinx
- Extension để auto build và livereload lại sphinx: sphix-autobuild, xem thêm tại
Viết tài liệu HDSD
Quy trình chung
Clone repo tài liệu
Tạo tài liệu
Publish tài liệu
Product Document và Knowledge Base
Cơ sở kiến thức (Knowledge base) và tài liệu sản phẩm (Product Document) được xây dựng và duy trì bởi các vị trí khác nhau và có nhiều thông tin giống nhau. Tùy thuộc vào vị trị và phụ tuộc vào loại và mục đích sử dụng của nội dung.
Thông thường:
- Tài liệu sản phẩm (Product Document, User guide) được xây dựng bởi team làm sản phẩm
- KB được xây dựng và duy trì bởi team support (help desks)
Tài liệu sản phẩm - Product document
- Tài liệu sản phẩm được xây dựng dựa trên chức năng của sản phẩm (tức là có tính chủ động)
- Nó cố gắng bao gồm tất cả các chức năng của sản phẩm
- Mọi tính năng của sản phẩm cần/nên được ghi lại, hướng dẫn lại ngay cả khi nó rất hiếm được sử dụng
- Không thảo luận về các hệ thống hoặc tích hợp bên ngoài trừ khi chúng là một phần chính thức của sản phẩm
Các bài viết cơ sở tri thức - Knowledge Base articles
- KB được xây dựng xung quanh các câu hỏi của khách hàng (tức là nó mang tính chất phản ứng hơn là chủ động)
- Trọng tâm cảu KB là khắc phụ sự cố, giải quyết tính huống
- Chủ đề bài viết KB xuất phát từ các câu hỏi phổ biến của khách hàng mà câu trả lời không có trong tài liệu sản phẩm.
- Mỗi bài viết có cấu trúc xoay quanh một vấn đề và một giải pháp.
Tham khảo:
- https://dzone.com/articles/product-documentation-vs-knowledge-base-1
- https://spaces.ais.ucla.edu/display/CMS/Product+Documentation+vs.+Knowledge+Base