Trang này được dịch bởi Cloud Translation API.

Dự án Tài nguyên quốc gia về sinh học mạng (NRNB)

Trang này chứa thông tin chi tiết về một dự án viết nội dung kỹ thuật đã được chấp nhận tham gia Google Season of Docs.

Tóm tắt dự án

Tổ chức nguồn mở:: Tài nguyên quốc gia về sinh học mạng (NRNB)
Người viết nội dung kỹ thuật:: Prubhtej_9
Tên dự án:: Tạo tài liệu hướng dẫn người dùng cho SynBioHub và phát triển hướng dẫn cho các trường hợp sử dụng cụ thể
Thời lượng dự án:: Thời gian tiêu chuẩn (3 tháng)

Mô tả dự án

Bản tóm tắt

Tài liệu người dùng được thiết kế để hỗ trợ người dùng cuối sử dụng một sản phẩm hoặc dịch vụ. Tài liệu người dùng tốt rất quan trọng vì nó cung cấp cho người dùng một phương tiện để tìm hiểu cách sử dụng phần mềm, các tính năng, mẹo và thủ thuật của phần mềm cũng như giải quyết các vấn đề thường gặp khi sử dụng phần mềm. Tài liệu này cũng giúp giảm chi phí hỗ trợ và là một phần của bản sắc doanh nghiệp của sản phẩm, tức là tài liệu người dùng tốt là dấu hiệu của một sản phẩm và nhóm nhà phát triển lành mạnh. Nếu không có tài liệu phù hợp với người dùng, người dùng có thể không biết cách thực hiện những thao tác nêu trên sao cho hiệu quả. Tài liệu hướng dẫn người dùng có thể đóng vai trò quan trọng trong việc đảm bảo sự thành công của một sản phẩm vì thông tin liên lạc hiệu quả luôn là yếu tố cốt lõi của mọi doanh nghiệp hoặc sản phẩm. Tài liệu hướng dẫn hiệu quả chỉ cần lấy thông tin liên lạc đó và đặt vào một khung quản lý mà mọi người đều có thể truy cập để đạt được thành công. SynBioHub là một kho lưu trữ thiết kế cho sinh học tổng hợp. Công cụ này được cung cấp cả dưới dạng trang web công khai và phần mềm nguồn mở. SynBioHub sử dụng Ngôn ngữ mở về sinh học tổng hợp (SBOL), một tiêu chuẩn nguồn mở để biểu thị các thiết kế di truyền, đồng thời cho phép chia sẻ các phần thiết kế từ GenBank và tệp FASTA. Bạn có thể dùng SynBioHub để phát hành thư viện các thiết kế và thành phần tổng hợp dưới dạng dịch vụ, chia sẻ thiết kế với cộng tác viên và lưu trữ thiết kế của các hệ thống sinh học trên máy. Bạn có thể truy cập dữ liệu trong SynBioHub qua API HTTP, API Java hoặc API Python. Sau đó, dữ liệu có thể được tích hợp vào các công cụ CAD để xây dựng các thiết kế di truyền. SynBioHub chứa một giao diện để người dùng tải dữ liệu sinh học mới lên cơ sở dữ liệu, để trực quan hoá các phần DNA, để thực hiện truy vấn nhằm truy cập vào các phần mong muốn và để tải SBOL, GenBank, FASTA, v.v. Nhiều bài báo nghiên cứu và một số hướng dẫn cũng có trên Internet, chẳng hạn như sau: 1. https://pubs.acs.org/doi/abs/10.1021/acssynbio.7b00403 2. https://pubs.acs.org/doi/abs/10.1021/acssynbio.0c00056 SynBioHub có một số tài liệu chỉ liên quan đến API, trong khi không có tài liệu nào cho GUI.

Trạng thái hiện tại của tài liệu:

Hiện tại, tài liệu người dùng có tại :“https://synbiohub.github.io/api-docs/#about-synbiohub “. Đây chỉ là tài liệu API và không có tài liệu GUI nào có thể giúp người dùng điều hướng trong kho lưu trữ thiết kế. Ngoài ra, tài liệu API cũng cần được cập nhật một chút, với một số chủ đề cụ thể như khắc phục sự cố của một số vấn đề đặc biệt mà người dùng có thể gặp phải. Tuy nhiên, tổ chức này đã quay một số video hướng dẫn, chẳng hạn như video tại đây. Thực sự không có tài liệu bằng văn bản nào dành cho người dùng về SynBioHub có thể hướng dẫn người dùng.

Tại sao tài liệu người dùng mà bạn đề xuất là một điểm cải tiến so với tài liệu hiện tại? Tôi sẽ xây dựng tài liệu về GUI từ đầu bằng cách sử dụng github và markdown theo đề xuất của người cố vấn, ông Chris Myers. Tài liệu người dùng được đề xuất sẽ được xây dựng theo cấu trúc để cải thiện và đảm bảo tính hiệu quả, tính nhất quán và sự an tâm cho mọi người dùng cuối. Tài liệu này sẽ chứa hướng dẫn bằng văn bản và hình ảnh liên quan, bao gồm hướng dẫn và giải thích về cách sử dụng từng tính năng của trình mô phỏng nguồn mở SynBioHub. Trong quá trình thảo luận với ông Myers, chúng tôi cũng quyết định rằng tài liệu API sẽ được hợp nhất với GUI và sẽ chứa 6 phần, trong đó phần 6 là không bắt buộc. Các phần được đề cập như sau: 1. Giới thiệu 2. Hướng dẫn cài đặt a) Từ hình ảnh tạo sẵn b) Từ nguồn c) Cấu hình NGINX 3. Hướng dẫn sử dụng a) Hướng dẫn chi tiết về cách sử dụng từng tính năng của GUI b) Hướng dẫn cho các trường hợp sử dụng phổ biến 4. Tài liệu về API – Mục 5 về Điểm cuối. Tài liệu về trình bổ trợ 6. Thông tin khắc phục sự cố và tham khảo sau này.

Phần 1:

Trong phần này, người dùng sẽ được cung cấp thông tin giới thiệu chi tiết và nhiều hướng dẫn liên quan đến SynBioHub.

Phần 2:

Trong phần này, người dùng có thể cài đặt phần mềm nguồn mở bằng nhiều phương thức, cụ thể là: a) Từ hình ảnh tạo sẵn b) Từ nguồn c) Cấu hình NGINX

Phần 3:

Đây là phần quan trọng nhất của tài liệu và sẽ chiếm nhiều thời gian nhất. Trong đó, mọi chi tiết nhỏ sẽ được thêm vào ngữ cảnh của GUI. Như đã đề cập ở trên, phần này chủ yếu sẽ giải quyết hai vấn đề, đó là hướng dẫn chi tiết về cách sử dụng từng tính năng GUI và một số hướng dẫn cho các trường hợp sử dụng phổ biến.

Phần 4:

Như đã đề cập ở trên, slate sẽ được dùng để tạo tài liệu cho phần này. Phần này sẽ bao gồm các điểm cuối sau: 1. Điểm cuối của người dùng 2. Điểm cuối tìm kiếm 3. Điểm cuối tải xuống 4. Tải điểm cuối xuống 5. Điểm cuối gửi 6. Điểm cuối quyền. 7. Chỉnh sửa Điểm cuối 8. Điểm cuối tệp đính kèm 9. Điểm cuối quản trị

Phần 5:

Trong phần này, tài liệu về trình bổ trợ sẽ được đưa vào tài liệu cũ của SynBioHub. Phần này sẽ được chia thành hai phần, cụ thể là: thông số kỹ thuật và triển khai trình bổ trợ. Phần 6: [Không bắt buộc] Phần này sẽ bao gồm danh sách các lỗi rất phổ biến mà người dùng gặp phải, cũng như một số hướng dẫn khắc phục sự cố. Theo cuộc thảo luận với ông Myers, chúng tôi đã quyết định có thể hợp nhất phần này với phần giới thiệu, nếu phần giới thiệu không quá dài. Phân tích Ông Myers và tôi đã trò chuyện về cách cập nhật tài liệu hiện có và cũng viết một tài liệu mới cho GUI. Trong một vài cuộc trò chuyện đó, chúng tôi đã xây dựng bố cục cơ bản cho tài liệu mới như đã đề cập ở trên và đưa ra tiến trình ước tính trên trang 5 bên dưới. Theo nội dung thảo luận, tôi sẽ sử dụng github và markdown để xây dựng tài liệu cho mọi phần, ngoại trừ Phần 4 của tài liệu, trong đó sẽ sử dụng slate. Slate: Slate giúp bạn tạo tài liệu API đẹp mắt, thông minh và thích ứng. Slate là một công cụ dựa trên Ruby, tạo ra một trang web tĩnh có tài liệu API gồm ba bảng điều khiển trông rất đẹp từ một tập hợp các tệp markdown. Ứng dụng này do nhà phát triển Robert Lord xây dựng vào năm 2013 khi anh là thực tập sinh 18 tuổi tại công ty phần mềm du lịch "Tripit". Anh đã thuyết phục được ông chủ của mình tại thời điểm đó cho phép anh phát hành dự án dưới dạng nguồn mở và phần còn lại là lịch sử. API này có những tính năng sau: • Thiết kế gọn gàng, trực quan — Với Slate, nội dung mô tả API nằm ở bên trái tài liệu, còn mọi đoạn mã ví dụ đều nằm ở bên phải. Lấy cảm hứng từ tài liệu API của Stripe và PayPal. Slate có khả năng thích ứng nên trông rất đẹp trên máy tính bảng, điện thoại và thậm chí là trên bản in. • Mọi thông tin trên một trang duy nhất — Không còn những ngày mà người dùng phải tìm kiếm trong cả triệu trang để tìm nội dung họ muốn. Slate đặt toàn bộ tài liệu trên một trang duy nhất. Tuy nhiên, chúng tôi vẫn không hy sinh khả năng liên kết. Khi bạn cuộn, hàm băm của trình duyệt sẽ cập nhật thành tiêu đề gần nhất, vì vậy, việc liên kết đến một điểm cụ thể trong tài liệu vẫn tự nhiên và dễ dàng. • Slate chỉ là Markdown — Khi viết tài liệu bằng Slate, bạn chỉ cần viết Markdown. Điều này giúp bạn dễ dàng chỉnh sửa và hiểu được tài liệu. Mọi thứ đều được viết bằng Markdown — ngay cả các mã mẫu cũng chỉ là các khối mã Markdown. • Viết mã mẫu bằng nhiều ngôn ngữ — Nếu API của bạn có các liên kết bằng nhiều ngôn ngữ lập trình, bạn có thể dễ dàng đặt các thẻ để chuyển đổi giữa các ngôn ngữ đó. Trong tài liệu, bạn sẽ phân biệt các ngôn ngữ khác nhau bằng cách chỉ định tên ngôn ngữ ở đầu mỗi khối mã, giống như với Markdown theo hương vị GitHub. • Tính năng đánh dấu cú pháp ngay từ đầu cho hơn 100 ngôn ngữ mà không cần định cấu hình. • Mục lục tự động, cuộn mượt mà ở phía ngoài cùng bên trái của trang. Khi bạn cuộn, thanh này sẽ hiển thị vị trí hiện tại của bạn trong tài liệu. Quá trình này cũng rất nhanh. Chúng tôi đang sử dụng Slate tại TripIt để xây dựng tài liệu cho API mới, trong đó mục lục có hơn 180 mục. Chúng tôi đảm bảo hiệu suất vẫn ở mức cao, ngay cả đối với các tài liệu lớn hơn. • Cho phép người dùng cập nhật tài liệu cho bạn – Theo mặc định, tài liệu do Slate tạo được lưu trữ trong một kho lưu trữ GitHub công khai. Điều này không chỉ giúp bạn có được dịch vụ lưu trữ miễn phí cho tài liệu của mình thông qua GitHub Pages, mà còn giúp các nhà phát triển khác dễ dàng gửi yêu cầu lấy dữ liệu cho tài liệu của bạn nếu họ phát hiện lỗi chính tả hoặc các vấn đề khác. Tất nhiên, nếu không muốn sử dụng GitHub, bạn cũng có thể lưu trữ tài liệu của mình ở nơi khác. • RTL Hỗ trợ bố cục đầy đủ từ phải sang trái cho các ngôn ngữ RTL như tiếng Ả Rập, tiếng Ba Tư (Farsi), tiếng Do Thái, v.v. Kết quả Slate là một trong những phần mềm nguồn mở mạnh mẽ nhất để tạo tài liệu và theo các cuộc thảo luận với người cố vấn của tôi, ông Chris Myers, tôi sẽ sử dụng slate cho Phần 4 và cho các phần khác, github và markdown sẽ được sử dụng. Bạn có thể xem thông tin chi tiết hơn về tài liệu này trong các phần bên dưới. Cấu trúc của tài liệu đề xuất Tôi đã tạo một cấu trúc cho Hướng dẫn sử dụng SynBioHub có thể tìm thấy trên trang 2. Cấu trúc này được chấp nhận và đã được ông Myers sửa đổi. Mục tiêu dự án 1. Điều chỉnh lại cấu trúc tài liệu. 2. Cập nhật tài liệu cho phù hợp với các phiên bản SynBioHub hiện đại. 3. Xoá thông tin lỗi thời. 4. Viết lại tài liệu người dùng cho dễ hiểu hơn. 5. Thêm một phần ngắn về điều kiện tiên quyết vào tài liệu dành cho những người đóng góp mới để tăng sự hiểu biết cơ bản của họ về các khái niệm sinh học cơ bản và giao diện của SynBioHub.