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 kỹ thuật được chấp nhận cho Phần Google Tài liệu.

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 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 hướng dẫn người dùng tốt là tài liệu rất quan trọng vì nó mang đến một không gian để người dùng tìm hiểu cách sử dụng phần mềm, các tính năng, mẹo, thủ thuật và cũng như giải quyết các vấn đề thường gặp khi sử dụng phần mềm. Ngoài ra, việc này còn giúp giảm chi phí hỗ trợ và là một phần trong bản sắc doanh nghiệp của sản phẩm, tức là tài liệu của người dùng hợp lệ là dấu hiệu cho thấy sản phẩm hoạt động tốt và nhóm nhà phát triển. Nếu không có tài liệu hướng dẫn cụ thể về người dùng, người dùng có thể sẽ không biết cách thực hiện những việc được đề cập ở trên một cách hiệu quả. Tài liệu về người dùng có thể đóng vai trò then chốt trong việc đảm bảo thành công của sản phẩm bởi vì khả năng giao tiếp hiệu quả sẽ luôn là yếu tố trọng tâm của mọi doanh nghiệp hoặc sản phẩm. Ngoài ra, một tài liệu tuyệt vời chỉ bao gồm thông tin liên lạc đó và đặt chúng trong một khuôn khổ dễ quản lý mà mọi người đều có thể truy cập để thành công. SynBioHub là một kho lưu trữ thiết kế dành cho sinh học tổng hợp. Công cụ này có sẵn 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ở sinh học tổng hợp (SBOL), một tiêu chuẩn nguồn mở để thể hiện thiết kế di truyền, đồng thời cho phép chia sẻ các phần thiết kế từ tệp GenBank và FASTA. Có thể sử dụng SynBioHub để xuất bản một thư viện gồm các bộ phận và thiết kế tổng hợp dưới dạng dịch vụ, để chia sẻ thiết kế với các 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. Dữ liệu trong SynBioHub có thể được truy cập qua API HTTP, Java API hoặc Python API. Sau đó, dữ liệu này 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. Tổng hợp /

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

Hiện tại, bạn có thể xem tài liệu về người dùng tại :“https://synbiohub.github.io/api-docs/#about-synbiohub”. Đây chỉ là tài liệu về API và không có tài liệu GUI (Giao diện người dùng đồ hoạ) 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 về 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 một số vấn đề đặc biệt mà người dùng có thể gặp phải. Mặc dù tổ chức đã ghi lại một số video hướng dẫn, chẳng hạn như video hướng dẫn tại đây. Thực sự không có tài liệu 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 về người dùng mà bạn đề xuất lại cải thiện hơn tài liệu hiện tại? Tôi sẽ xây dựng tài liệu GUI từ đầu bằng cách sử dụng github và đánh dấu theo đề xuất của cố vấn Chris Myers. Tài liệu dành cho người dùng mà bạn đề xuất sẽ được 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 bất kỳ người dùng cuối nào. Tài liệu này có hướng dẫn bằng văn bản và hình ảnh liên quan, kèm theo hướng dẫn và nội dung giải thích cách sử dụng từng tính năng của SynBioHub trình mô phỏng nguồn mở. Trong các cuộc thảo luận với ông Myers, người ta 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 này đượ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 GUI b) Hướng dẫn các trường hợp sử dụng phổ biến 4. Tài liệu API – Điểm cuối phần 5. Tài liệu về trình bổ trợ 6. Khắc phục sự cố và các tài liệu tham khảo trong tương lai.

Phần-1:

Trong phần này, người dùng sẽ được cung cấp phần giới thiệu chi tiết và nhiều hướng dẫn về 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ở theo những cách khác nhau, 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 giấy tờ và sẽ chiếm hầu hết thời gian. Tại đây, thông tin chi tiết từng phút sẽ được thêm vào ngữ cảnh của GUI (Giao diện người dùng đồ hoạ). Như đã đề cập ở trên, chủ yếu sẽ giải quyết hai mối lo ngại trong phần này, đó 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, phương tiện chặn sẽ được dùng để tạo tài liệu về phần này. Trong phần này, sẽ có các điểm cuối sau đây: 1. Điểm cuối của người dùng 2. Điểm cuối tìm kiếm 3. Tải xuống thiết bị đầu cuối 4. Tải điểm cuối xuống 5. Điểm cuối gửi 6. Điểm cuối của quyền. 7. Chỉnh sửa điểm cuối 8. Điểm cuối đính kèm 9. Thiết bị đầu 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 và tài liệu này đã có trong tài liệu cũ của SynBioHub. Phần này sẽ được chia thành hai phần, cụ thể là: quy cách trình bổ trợ và cách triển khai. Phần 6: [Không bắt buộc] Phần này sẽ bao gồm một danh sách lỗi rất phổ biến mà người dùng gặp phải và cũng sẽ bao gồm một số hướng dẫn khắc phục sự cố. Theo cuộc thảo luận với Mr Myers, chúng tôi đã quyết định rằng phần này có thể được hợp nhất với phần giới thiệu nếu không quá dài. Tôi và ông Myers đã thảo luận về cách cập nhật tài liệu hiện có cũng như cách viết một tài liệu mới cho GUI (Giao diện người dùng đồ hoạ). Trong vài cuộc trò chuyện đó, chúng tôi đã hình thành bố cục cơ bản cho tài liệu mới đã đề cập ở trên và tiến trình ước tính đã được đưa ra ở trang 5 dưới đây. Theo cuộc thảo luận, tôi sẽ sử dụng github và đánh dấu để 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 đó phương tiện chặn sẽ được sử dụng. Slate:– Slate giúp bạn tạo tài liệu về API đẹp mắt, thông minh và có tính phản hồi nhanh. Slate là một công cụ dựa trên Ruby, tạo ra một trang web tĩnh của tài liệu API ba bảng đẹp mắt từ một tập hợp các tệp đánh dấu. Nó được nhà phát triển Robert Lord xây dựng vào năm 2013 khi anh là một 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 sếp của mình vào thời điểm đó cho phép anh mở nguồn cho dự án này và phần còn lại đã đi vào lịch sử. Mã này có các tính năng sau: • Thiết kế gọn gàng, trực quan — Với Slate, phần mô tả API nằm ở bên trái tài liệu và tất cả các mã ví dụ nằm ở bên phải. Lấy cảm hứng từ các tài liệu API của Stripe và PayPal. Slate có tính thích ứng, vì vậy, giao diện này trông rất tuyệt trên máy tính bảng, điện thoại và thậm chí cả trên bản in. • Mọi thứ trên một trang — Đã qua rồi cái thời người dùng phải tìm kiếm qua hàng triệu trang để tìm nội dung họ muốn. Phương tiện chặn đặt toàn bộ tài liệu trên một trang duy nhất. Tuy nhiên, chúng tôi không từ bỏ 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ính là Markdown — Khi viết tài liệu bằng Slate, bạn chỉ đang viết Markdown để việc chỉnh sửa và hiểu nội dung trở nên đơn giản. Mọi thứ đều được viết trong Markdown – thậm chí cả các mã mẫu 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ó 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 GitHub Flavored Markdown. • Đánh dấu cú pháp ngay từ đầu cho hơn 100 ngôn ngữ, không cần phải định cấu hình. • Mục lục cuộn tự động, đều đặn ở ngoài cùng bên trái của trang. Khi bạn di chuyển, hệ thống sẽ hiển thị vị trí hiện tại của bạn trong tài liệu. Cũng nhanh chóng. Chúng tôi đang sử dụng Slate tại TripIt để xây dựng tài liệu cho API mới của chúng tôi, nơi mục lục của chúng tôi có hơn 180 mục nhập. Chúng tôi đảm bảo rằng hiệu suất vẫn ở mức tuyệt vời, 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 giúp bạn — Theo mặc định, tài liệu do Slate tạo ra được lưu trữ trong một kho lưu trữ GitHub công khai. Điều này không chỉ có nghĩa là bạn có thể lưu trữ miễn phí tài liệu của mình qua Trang GitHub, mà còn giúp các nhà phát triển khác dễ dàng đưa ra yêu cầu kéo tài liệu của bạn nếu họ tìm thấy lỗi chính tả hoặc các vấn đề khác. Tất nhiên, nếu không muốn dùng GitHub, bạn cũng có thể lưu trữ tài liệu của mình ở nơi khác. • Hỗ trợ RTL 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. Verdict 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 cố vấn của tôi, thầy Chris Myers sẽ sử dụng phương tiện chặn cho Phần 4 và cho các phần khác, github và đánh dấu sẽ được sử dụng. Chế độ xem chi tiết hơn của tài liệu sẽ được thảo luận trong các phần dưới đây. Cấu trúc của tài liệu được đề xuất Tôi đã xây dựng cấu trúc cho Hướng dẫn sử dụng SynBioHub ở trang 2. Cấu trúc này đã được chấp nhận và đã được ông Myers sửa đổi. Mục tiêu của dự án 1. Điều chỉnh cấu trúc tài liệu. 2. Cập nhật tài liệu cho phù hợp với 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. Đưa một phần ngắn gọ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 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.