이 페이지에는 Google Season of Docs에 선정된 기술 문서 프로젝트의 세부정보가 포함되어 있습니다.
프로젝트 요약
- 오픈소스 구성:
- NRNB (National Resource for Network Biology)
- 기술 문서 작성자:
- Prubhtej_9
- 프로젝트 이름:
- SynBioHub용 사용자 문서를 만들고 특정 사용 사례에 관한 튜토리얼을 개발합니다.
- 프로젝트 길이:
- 표준 기간 (3개월)
Project description
개요
사용자 문서는 최종 사용자가 제품 또는 서비스를 사용하는 데 도움을 주기 위해 설계되었습니다. 우수한 사용자 문서는 사용자가 소프트웨어 사용 방법, 기능, 도움말, 요령을 학습하고 소프트웨어 사용 시 발생하는 일반적인 문제를 해결할 수 있는 수단을 제공하므로 매우 중요합니다. 또한 지원 비용을 줄이고 제품의 기업 이미지에 포함됩니다. 즉, 우수한 사용자 문서는 건강한 제품과 개발자팀의 신호입니다. 우수한 사용자 문서가 없으면 사용자가 위에 언급된 작업을 효과적이고 효율적으로 수행하는 방법을 알지 못할 수 있습니다. 사용자 문서는 제품의 성공을 보장하는 데 중요한 역할을 할 수 있습니다. 효과적인 커뮤니케이션은 항상 모든 비즈니스 또는 제품의 핵심이며 우수한 문서는 이러한 커뮤니케이션을 모든 사용자가 성공을 위해 액세스할 수 있는 관리 가능한 프레임워크에 담아냅니다. SynBioHub는 합성 생물학을 위한 설계 저장소입니다. 공개 웹사이트와 오픈소스 소프트웨어로 모두 제공됩니다. SynBioHub는 유전학적 설계를 나타내는 오픈소스 표준인 합성 생물학 개방형 언어 (SBOL)를 사용하며 GenBank 및 FASTA 파일의 설계 부품을 공유할 수도 있습니다. SynBioHub는 합성 부품 및 설계 라이브러리를 서비스로 게시하고, 공동작업자와 설계를 공유하고, 생물학적 시스템의 설계를 로컬에 저장하는 데 사용할 수 있습니다. SynBioHub의 데이터는 HTTP API, Java API 또는 Python API를 통해 액세스할 수 있으며, 이를 CAD 도구에 통합하여 유전 설계를 구축할 수 있습니다. SynBioHub에는 사용자가 데이터베이스에 새로운 생물학적 데이터를 업로드하고, DNA 부품을 시각화하고, 원하는 부품에 액세스하기 위한 쿼리를 실행하고, SBOL, GenBank, FASTA 등을 다운로드할 수 있는 인터페이스가 포함되어 있습니다. 다음과 같은 다양한 연구 논문과 튜토리얼도 인터넷에서 확인할 수 있습니다. 1. https://pubs.acs.org/doi/abs/10.1021/acssynbio.7b00403 2. https://pubs.acs.org/doi/abs/10.1021/acssynbio.0c00056 SynBioHub에는 API와만 관련된 문서가 있지만 GUI에 관한 문서는 없습니다.
문서의 현재 상태:
현재 사용자 문서는 'https://synbiohub.github.io/api-docs/#about-synbiohub'에서 확인할 수 있습니다. 이는 API 문서일 뿐이며 사용자가 디자인 저장소 내에서 탐색하는 데 도움이 되는 GUI 문서는 없습니다. 또한 API 문서도 사용자에게 발생할 수 있는 특정 문제 해결과 같은 몇 가지 구체적인 주제로 업데이트가 필요합니다. 조직에서 녹화한 튜토리얼 동영상이 있습니다(예: 여기의 동영상). 사용자를 안내할 수 있는 SynBioHub에 관한 서면 사용자 문서가 없습니다.
제안된 사용자 문서가 현재 문서보다 개선된 이유는 무엇인가요? 멘토인 크리스 마이어스가 제안한 대로 GitHub와 마크다운을 사용하여 GUI 문서를 처음부터 작성할 것입니다. 제안된 사용자 문서는 모든 최종 사용자의 효율성, 일관성, 안심할 수 있는 환경을 개선하고 보장하도록 구성됩니다. 이 가이드에는 서면 가이드와 관련 이미지가 포함되며 오픈소스 시뮬레이터 SynBioHub의 각 기능을 사용하는 방법에 관한 안내와 설명이 포함됩니다. Myers 씨와 논의하는 동안 API 문서가 GUI와 병합되고 6개의 섹션이 포함되고 , 그 중 6번째 섹션은 선택 사항이 되기로 결정했습니다. 섹션은 다음과 같이 언급됩니다. 1. 머리말 2. 설치 안내 a) 사전 빌드된 이미지에서 b) 소스에서 c) NGINX 구성 3. 사용자 안내 a) 각 GUI 기능 사용 방법에 관한 자세한 안내 b) 일반적인 사용 사례에 관한 튜토리얼 4. API 문서 - 엔드포인트 섹션 5 플러그인 문서 6. 문제 해결 및 향후 참고 자료
파트 1:
이 섹션에서는 사용자에게 SynBioHub에 관한 자세한 소개와 다양한 튜토리얼을 제공합니다.
2단계:
이 섹션에서는 사용자가 다양한 방법을 사용하여 오픈소스 소프트웨어를 설치할 수 있는 다양한 방법을 설명합니다. 즉, a) 사전 빌드된 이미지에서 b) 소스에서 c) NGINX 구성
Part-3:
이는 문서에서 가장 중요한 부분이며 대부분의 시간을 차지합니다. 여기에서 GUI에 모든 세부정보가 컨텍스트로 추가됩니다. 위에서 언급한 바와 같이 이 섹션에서는 주로 두 가지 문제, 즉 각 GUI 기능을 사용하는 방법에 관한 자세한 안내와 일반적인 사용 사례에 관한 몇 가지 튜토리얼을 다룹니다.
파트 4:
위에서 언급했듯이 슬레이트는 이 부분의 문서를 생성하는 데 사용됩니다. 이 섹션에는 다음 엔드포인트가 포함됩니다. 1. 사용자 엔드포인트 2. Search Endpoints 3. Endpoints 4를 다운로드합니다. Endpoints 5를 다운로드합니다. 제출 엔드포인트 6. 권한 엔드포인트 7. 엔드포인트 수정 8. 첨부파일 엔드포인트9. 관리 엔드포인트
5부:
이 섹션에는 이전 SynBioHub 문서에 이미 있는 플러그인 문서가 포함됩니다. 이 섹션은 플러그인 사양과 구현이라는 두 섹션으로 세분화됩니다. 6단계: [선택사항] 이 섹션에는 사용자가 겪는 매우 일반적인 오류 목록과 몇 가지 문제 해결 안내가 포함됩니다. Myers와 논의한 바에 따라 이 섹션은 시간이 오래 걸리지 않는다면 소개 섹션과 병합할 수 있다고 결정되었습니다. 분석 마이어스님과 저는 기존 문서를 업데이트하고 GUI용 새 문서를 작성하는 방법에 관해 대화를 나눴습니다. 몇 번의 대화를 통해 위에서 언급한 새 문서의 기본 레이아웃을 수립했으며 아래 5페이지에 예상 일정이 제공되었습니다. 논의에 따라 슬레이트가 사용되는 문서의 4단계를 제외한 모든 섹션의 문서를 빌드하는 데 GitHub 및 마크다운을 사용하겠습니다. Slate:- Slate를 사용하면 아름답고 지능적이며 반응형 API 문서를 만들 수 있습니다. Slate는 마크다운 파일 집합에서 세 개의 패널로 구성된 멋진 API 문서 정적 사이트를 생성하는 Ruby 기반 도구입니다. 여행 소프트웨어 회사인 'Tripit'에서 18세의 인턴으로 근무한 2013년 개발자 로버트 로드가 빌드했습니다. 당시 상사에게 프로젝트를 오픈소스로 제공하도록 하고 나머지는 역사였습니다. 다음과 같은 기능이 있습니다. • 깔끔하고 직관적인 디자인: Slate를 사용하면 API 설명이 문서의 왼쪽에 있고 모든 코드 예시가 오른쪽에 표시됩니다. Stripe 및 PayPal의 API 문서에서 영감을 얻었습니다. Slate는 반응형이므로 태블릿, 휴대전화, 인쇄물에서도 멋지게 표시됩니다. • 한 페이지에 모든 정보 표시 - 사용자가 원하는 정보를 찾기 위해 수백만 개의 페이지를 검색해야 했던 시대는 지났습니다. Slate는 전체 문서를 한 페이지에 표시합니다. 연결 가능성은 그대로 유지했습니다. 스크롤하면 브라우저의 해시가 가장 가까운 헤더로 업데이트되므로 문서의 특정 지점으로 자연스럽고 쉽게 연결할 수 있습니다. • Slate는 마크다운에 불과합니다. Slate로 문서를 작성하면 간단하게 수정하고 이해할 수 있는 마크다운을 작성하게 됩니다. 모든 것이 마크다운으로 작성됩니다. 코드 샘플도 마크다운 코드 블록일 뿐입니다. • 여러 언어로 코드 샘플 작성 — API에 여러 프로그래밍 언어로 된 바인딩이 있는 경우 탭을 쉽게 추가하여 언어 간에 전환할 수 있습니다. 문서에서는 GitHub 맞춤형 마크다운과 마찬가지로 각 코드 블록 상단에 언어 이름을 지정하여 다양한 언어를 구분할 수 있습니다. • 100개가 넘는 언어를 위한 즉시 사용 가능한 구문 강조 표시 기능(구성 필요 없음) • 페이지 왼쪽에 있는 목차가 자동으로 부드럽게 스크롤됩니다. 스크롤하면 문서의 현재 위치가 표시됩니다. 속도도 빠릅니다. TripIt에서는 Slate를 사용하여 새로운 API의 문서를 작성하고 있으며, 목차에는 180개가 넘는 항목이 있습니다. 대용량 문서에서도 우수한 성능을 유지할 수 있도록 했습니다. • 사용자가 문서를 업데이트하도록 허용 - 기본적으로 Slate에서 생성된 문서는 공개 GitHub 저장소에 호스팅됩니다. 이렇게 하면 GitHub Pages를 통해 문서를 무료로 호스팅할 수 있을 뿐만 아니라 다른 개발자가 오타나 기타 문제를 발견하면 간편하게 문서에 대한 풀 요청을 할 수 있습니다. 물론 GitHub를 사용하고 싶지 않다면 다른 곳에서 문서를 호스팅해도 됩니다. • RTL 지원: 아랍어, 페르시아어 (파르시어), 히브리어와 같은 RTL 언어의 전체 오른쪽에서 왼쪽 레이아웃을 지원합니다. 확인 결과 Slate는 문서를 생성하는 가장 강력한 오픈소스 소프트웨어 중 하나이며, 멘토인 크리스 마이어스와의 논의에 따라 4단계에서는 Slate를 사용하고 다른 부분에서는 github와 markdown을 사용하겠습니다. 문서의 자세한 내용은 아래 섹션에서 설명합니다. 제안된 문서의 구조: 2페이지에서 확인할 수 있는 SynBioHub 사용자 가이드의 구조를 만들었습니다. 이 구조는 허용되며 이미 마이어스님이 수정했습니다. 프로젝트 목표 1. 문서 구조를 변경합니다. 2. 최신 버전의 SynBioHub에 맞게 문서를 업데이트했습니다. 3. 오래된 정보를 삭제합니다. 4. 이해하기 쉽게 사용자 문서를 다시 작성합니다. 5. 새로운 도움을 주신 분들이 기본적인 생물학적 개념과 SynBioHub의 인터페이스에 대한 기본적인 이해도를 높일 수 있도록 설명서에 필요한 내용을 간단히 설명하는 섹션 포함