Visual Paradigm OpenDocs: Hướng dẫn thực tiễn

Hình tổng quan giới thiệu OpenDocs như một nơi để tạo biểu đồ, cùng nhau ghi chép tài liệu, tổ chức tri thức và chia sẻ hoặc công bố kết quả. Một cách làm việc hữu ích là coi mỗi tài liệu là một phần của cơ sở tri thức được duy trì, chứ không phải là một tệp đơn lẻ.

OpenDocs được mô tả là một môi trường quản lý tri thức và ghi chép tài liệu dựa trên web, kết hợp nội dung văn bản với các mô hình trực quan. Pipeline của Visual Paradigm cũng có thể liên kết các biểu đồ được tạo trong Visual Paradigm Desktop hoặc Online với OpenDocs, giúp giảm sự phụ thuộc vào các hình ảnh tĩnh được xuất thủ công. Các khả năng có sẵn có thể phụ thuộc vào phiên bản và cấu hình Visual Paradigm của bạn.

1. Lập kế hoạch cho cơ sở tri thức

Trước khi viết các trang, hãy quyết định không gian này dùng để làm gì và ai sẽ sử dụng nó. Một cấu trúc tập trung sẽ giúp mọi người dễ dàng tìm kiếm và duy trì thông tin hơn.

Ví dụ, một cơ sở tri thức về sản phẩm hoặc hệ thống có thể được sắp xếp như sau:

• Tổng quan — mục đích, phạm vi, chủ sở hữu và liên kết đến các trang chính

• Kiến trúc — ngữ cảnh hệ thống, các thành phần, tích hợp và triển khai

• Quy trình — luồng công việc, quy trình và các điểm ra quyết định

• Dữ liệu — thực thể, luồng dữ liệu và định nghĩa

• Vận hành — sách hướng dẫn vận hành, giám sát, khôi phục và liên hệ hỗ trợ

• Quyết định — các lựa chọn thiết kế, lý do và hệ quả

• Từ điển thuật ngữ — thuật ngữ chung và các từ viết tắt

Giữ cấp độ cao nhất gọn nhẹ. Đặt nội dung chi tiết vào các trang con tập trung và liên kết các trang có liên quan với nhau.

2. Tạo một trang tổng quan rõ ràng

Bắt đầu bằng một trang giúp người đọc mới định hướng. Bao gồm:

1. Mục đích: Cơ sở tri thức này bao gồm những gì.

2. Đối tượng: Ai nên sử dụng nó.

3. Phạm vi: Những gì được bao gồm—và, nếu hữu ích, những gì không được bao gồm.

4. Quyền sở hữu: Ai chịu trách nhiệm duy trì nội dung.

5. Điều hướng: Các liên kết đến các phần quan trọng nhất.

6. Tính cập nhật: Ngày xem xét hoặc hướng dẫn để báo cáo nội dung đã lỗi thời.

Viết cho những độc giả chưa biết về dự án. Viết rõ các từ viết tắt ít phổ biến và giải thích ngữ cảnh đằng sau các sơ đồ quan trọng.

3. Soạn thảo và cấu trúc nội dung

OpenDocs hỗ trợ việc soạn thảo tài liệu và nội dung trực quan trong cùng một không gian làm việc. Kết quả tìm kiếm mô tả một trình soạn thảo định hướng Markdown và, trong một số quy trình làm việc, trải nghiệm chỉnh sửa WYSIWYG; hãy sử dụng chế độ chỉnh sửa có sẵn trong tài khoản của bạn.

Một mẫu trang đáng tin cậy là:

• Tóm tắt: Điểm chính trong vài câu.

• Bối cảnh: Tại sao chủ đề này quan trọng và những giả định nào được áp dụng.

• Trực quan: Một sơ đồ giải thích cấu trúc, hành vi hoặc mối quan hệ.

• Chi tiết: Định nghĩa, các bước, quy tắc hoặc giải thích hỗ trợ.

• Các trang liên quan: Các liên kết đến tài liệu tiên quyết và tài liệu tiếp theo.

• Chủ sở hữu và ngày xem xét: Ai kiểm tra trang và khi nào.

Ưu tiên các tiêu đề mô tả, các đoạn văn ngắn và danh sách cho các quy trình. Sử dụng bảng khi độc giả cần so sánh các trường hoặc quét các sự kiện có cấu trúc. Tránh để sơ đồ mang thông tin mà văn bản không bao giờ giải thích.

4. Chọn sơ đồ trả lời một câu hỏi

Chọn một mô hình trực quan dựa trên vấn đề mà bạn muốn độc giả hiểu:

• Sơ đồ luồng hoặc BPMN: Điều gì xảy ra và theo thứ tự nào?

• Sơ đồ trường hợp sử dụng hoặc hoạt động UML: Ai tương tác với hệ thống và hành vi nào xảy ra?

• Sơ đồ thành phần hoặc triển khai UML:Các bộ phận là gì và chúng được sắp xếp như thế nào?

• Sơ đồ trình tự:Các bên tham gia giao tiếp với nhau theo thời gian như thế nào?

• ERD:Các thực thể dữ liệu nào tồn tại và chúng liên quan với nhau như thế nào?

• Sơ đồ tư duy hoặc sơ đồ khái niệm:Các ý tưởng được nhóm và kết nối như thế nào?

• Biểu đồ Gantt, lộ trình hoặc cấu trúc phân chia công việc:Công việc nào được lên kế hoạch và chúng được phối hợp với nhau như thế nào?

Tài liệu của Visual Paradigm mô tả các quy trình làm việc của OpenDocs liên quan đến các loại sơ đồ như UML, BPMN, ERD, sơ đồ tư duy và các hình ảnh lập kế hoạch dự án. Hãy xác nhận rằng một loại sơ đồ cụ thể có sẵn trong phiên bản của bạn trước khi xây dựng quy trình xung quanh nó.

Đặt tiêu đề và một giải thích ngắn gọn cho mỗi sơ đồ. Định nghĩa các từ viết tắt, ghi nhãn các ranh giới quan trọng và giữ mức độ chi tiết phù hợp với đối tượng. Nếu một sơ đồ trở nên khó đọc, hãy chia nó thành một cái nhìn tổng quan và một hoặc nhiều cái nhìn chi tiết.

5. Thêm các sơ đồ vào tài liệu

Hình ảnh tổng quan gợi ý một chu kỳ biên tập đơn giản: tạo một hình ảnh trực quan, đặt nó ở vị trí hỗ trợ văn bản và giải thích cách đọc nó.

Một trình tự thực tế là:

1. Viết phần giải thích xung quanh trước, để sơ đồ có mục đích rõ ràng.

2. Tạo sơ đồ trong trình soạn thảo hoặc công cụ mô hình hóa có sẵn cho bạn.

3. Chèn hoặc nhúng nó vào trang liên quan bằng cách sử dụng tính năng tích hợp có sẵn trong tài khoản của bạn.

4. Thêm chú thích hoặc văn bản gần đó mô tả phạm vi và thông điệp chính của nó.

5. Kiểm tra xem các nhãn có thể đọc được ở độ rộng trang mà người đọc sẽ sử dụng hay không.

6. Xem lại trang dưới góc độ của người đọc, không chỉ trong chế độ chỉnh sửa.

Khi các sơ đồ được gửi qua Pipeline của Visual Paradigm, các nguồn mô tả một quy trình làm việc để cung cấp các đối tượng mô hình cho OpenDocs và chọn chúng để sử dụng trong tài liệu. Điều này có thể giúp giảm số lượng bản sao lỗi thời, nhưng các nhóm vẫn cần xác minh rằng đối tượng nhúng trỏ đến mô hình và phiên bản dự định.

6. Hợp tác với quy trình xem xét nhẹ nhàng

Sử dụng một quy trình nhất quán để việc hợp tác cải thiện độ chính xác thay vì tạo ra các chỉnh sửa mâu thuẫn:

1. Phân công trách nhiệm:Chỉ định một chủ sở hữu cho mỗi trang hoặc phần quan trọng.

2. Soạn thảo:Viết nội dung và bao gồm các hình ảnh trực quan cần thiết để giải thích nó.

3. Xem xét:Yêu cầu một chuyên gia về chủ đề kiểm tra tính chính xác và một người đọc bên ngoài nhóm trực tiếp kiểm tra tính rõ ràng.

4. Giải quyết các thay đổi:Đồng ý về các chỉnh sửa đối với cả văn bản và sơ đồ.

5. Xuất bản hoặc chia sẻ:Cung cấp phiên bản đã được xem xét cho đối tượng mục tiêu.

6. Xem xét lại:Xem xét lại trang khi hệ thống hoặc quy trình thay đổi.

Hình ảnh mô tả sự cộng tác của nhóm, nhưng các kiểm soát cộng tác chính xác và tính khả dụng có thể khác nhau. Hãy kiểm tra các kiểm soát được hiển thị trong không gian làm việc OpenDocs của bạn thay vì giả định rằng mọi tài khoản đều hỗ trợ cùng các tùy chọn chia sẻ hoặc chỉnh sửa.

7. Tổ chức và duy trì cơ sở tri thức

Một cơ sở tri thức tốt cần được chăm sóc liên tục. Giữ các trang đủ nhỏ để dễ dàng quét, sử dụng tiêu đề thống nhất và liên kết các chủ đề liên quan thay vì sao chép cùng một giải thích ở nhiều nơi.

Đối với mỗi trang quan trọng, hãy theo dõi:

• Một chủ sở hữu rõ ràng

• Đối tượng mục tiêu

• Nguồn sự thật cho các mô hình hoặc dữ liệu được liên kết

• Ngày xem xét lần cuối

• Bất kỳ hạn chế đã biết hoặc câu hỏi chưa được giải quyết nào

Khi một sơ đồ thay đổi, hãy xem xét lại cả văn bản xung quanh nó. Hình ảnh có thể còn mới trong khi phần giải thích, thuật ngữ hoặc quy trình được liên kết thì không.

8. Chia sẻ hoặc xuất bản một cách cân nhắc

Trước khi chia sẻ một trang hoặc không gian, hãy kiểm tra:

• Liệu đối tượng mục tiêu có thể truy cập nó hay không

• Liệu nội dung có bao gồm thông tin nhạy cảm hoặc chỉ dành cho nội bộ hay không

• Liệu chế độ xem được chia sẻ có hiển thị sơ đồ và bố cục như mong đợi hay không

• Liệu người nhận cần một trang đơn lẻ hay toàn bộ cơ sở tri thức

• Liệu tài liệu đã sẵn sàng cho độc giả bên ngoài hay chưa

Các tùy chọn chia sẻ và xuất bản chính xác phụ thuộc vào tài khoản và cấu hình. Hãy coi giai đoạn ‘Chia sẻ’ trong hình ảnh tổng quan là mục tiêu quy trình làm việc, chứ không phải là sự đảm bảo về một điểm đến xuất bản cụ thể hoặc mô hình quyền hạn.

9. Danh sách kiểm tra trang có thể tái sử dụng

Trước khi coi một trang là sẵn sàng, hãy xác nhận rằng nó:

• Có tiêu đề và mục đích rõ ràng

• Có ý nghĩa đối với đối tượng mục tiêu

• Định nghĩa các thuật ngữ chưa quen thuộc

• Sử dụng các sơ đồ trả lời các câu hỏi cụ thể

• Giải thích các hình ảnh quan trọng trong văn bản

• Liên kết đến các trang liên quan và tài liệu nguồn

• Xác định chủ sở hữu và ngày xem xét

• Đã được kiểm tra ở chế độ chia sẻ hoặc chế độ dành cho người đọc

Quy trình làm việc mẫu

Để tài liệu hóa một dịch vụ mới, hãy bắt đầu bằng một trang tổng quan giải thích mục đích và chủ sở hữu của nó. Thêm sơ đồ ngữ cảnh hệ thống để hiển thị người dùng và các phụ thuộc bên ngoài của nó. Tạo sơ đồ thành phần cho các phần chính của nó, sau đó tài liệu hóa các luồng yêu cầu chính và quy trình vận hành trên các trang riêng biệt. Liên kết các trang từ trang tổng quan, xem xét chúng cùng với nhóm dịch vụ và chia sẻ chế độ phù hợp với đối tượng mục tiêu. Nếu mô hình nền tảng thay đổi, hãy cập nhật hoặc kiểm tra lại hình ảnh được liên kết và phần giải thích của nó.

Nguyên tắc cốt lõi rất đơn giản: giữ cho quá trình viết, sơ đồ, tổ chức và chia sẻ được liên kết với nhauĐó chính là điều biến một bộ sưu tập các trang và hình ảnh thành tài liệu hữu ích và dễ bảo trì.

This post is also available in Deutsch, English, Español, فارسی, Français, Bahasa Indonesia, 日本語, Polski, Portuguese, Ру́сский, 简体中文 and 繁體中文.