이 페이지에는 Google Season of Docs에서 승인된 테크니컬 라이팅 프로젝트의 세부정보가 포함되어 있습니다.
프로젝트 요약
- 오픈소스 조직:
- 네트워크 생물학 국가 리소스 (NRNB)
- 테크니컬 라이터:
- Prubhtej_9
- 프로젝트 이름:
- SynBioHub 사용자 문서 작성 및 특정 사용 사례에 대한 튜토리얼 개발
- 프로젝트 기간:
- 표준 기간 (3개월)
Project description
개요
사용자 문서는 최종 사용자가 제품 또는 서비스를 사용하는 데 도움을 주기 위해 작성되었습니다. 양질의 사용자 문서는 사용자가 소프트웨어 사용 방법, 기능, 도움말, 유용한 정보를 배우고 소프트웨어 사용 시 발생하는 일반적인 문제를 해결하는 방법을 제공하기 때문에 매우 중요합니다. 또한 지원 비용을 줄일 수 있으며 제품의 기업 정체성의 일부이기도 합니다. 예를 들어 사용자 문서가 우수하다는 것은 제품과 개발자 팀이 건강한 제품이라는 표시입니다. 양질의 사용자 문서가 없으면 사용자는 위에 언급된 작업을 효과적이고 효율적으로 수행하는 방법을 알 수 없습니다. 사용자 문서는 제품의 성공을 보장하는 데 중추적인 역할을 할 수 있습니다. 모든 비즈니스 또는 제품의 중심에는 훌륭한 의사소통이 있기 때문입니다. 훌륭한 문서는 이러한 커뮤니케이션을 누구나 쉽게 사용할 수 있도록 관리 가능한 프레임워크로 만들어 주기 때문에 언제나 그 중심에 놓여 있기 때문입니다. SynBioHub는 합성생물학을 위한 디자인 저장소입니다. 공개 웹사이트와 오픈소스 소프트웨어로 모두 사용할 수 있습니다. SynBioHub는 유전자 디자인을 표현하는 오픈소스 표준인 Synthetic Biology Open Language (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.102의
문서 현재 상태:
현재 사용자 문서는 '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 구성
파트 3:
이 부분은 문서 작성에서 가장 중요한 부분이며 대부분의 시간을 차지합니다. 여기에서는 매분 세부정보가 GUI에 컨텍스트에 추가됩니다. 위에서 언급했듯이 이 섹션에서는 각 GUI 기능의 사용 방법에 대한 자세한 안내와 일반적인 사용 사례에 대한 튜토리얼이라는 두 가지 우려사항을 주로 다룹니다.
파트 4:
위에서 언급했듯이 이 부분에 대한 문서를 생성하는 데 슬레이트가 사용됩니다. 이 섹션에는 다음 엔드포인트가 포함됩니다. 1. 사용자 엔드포인트 2. 검색 엔드포인트 3. 엔드포인트 4를 다운로드합니다. 엔드포인트를 다운로드합니다. 5. 제출 엔드포인트 6. 권한 엔드포인트 7. 엔드포인트를 수정합니다. 8. 연결 엔드포인트 9. 관리 엔드포인트
파트 5:
이 섹션에는 기존 SynBioHub 문서에 있는 플러그인 문서가 포함됩니다. 이 섹션은 플러그인 사양과 구현이라는 두 섹션으로 세분화됩니다. 파트 6: [선택사항] 이 섹션에는 사용자에게 발생하는 매우 일반적인 오류 목록과 문제 해결 안내가 포함되어 있습니다. 마이어스 씨와의 논의에 따라, 이 섹션은 너무 길지 않다면 소개 섹션과 병합하기로 결정했습니다. 분석 마이어스 씨와 저는 기존 문서를 업데이트하는 방법과 GUI의 새 문서를 작성하는 방법에 관해 대화를 나누었습니다. 이러한 몇 개의 대화에서 위에서 언급한 새 문서의 기본 레이아웃을 공식화했으며, 아래 5페이지에 예상 타임라인이 나와 있습니다. 논의한 바와 같이, 슬레이트가 사용될 문서의 파트 4를 제외한 모든 섹션의 문서를 작성하기 위해 github와 마크다운을 사용할 것입니다. 슬레이트:- 슬레이트를 사용하면 아름답고 지능적이며 반응이 뛰어난 API 문서를 만들 수 있습니다. Slate는 마크다운 파일 집합에서 3개의 패널로 구성된 멋진 API 문서 정적 사이트를 생성하는 Ruby 기반 도구입니다. 2013년 여행 소프트웨어 회사 'Tripit'에서 18살로 인턴으로 근무했을 때 개발자 로버트 로드가 만들었습니다. 당시 상사에게 프로젝트를 오픈소스로 제공할 수 있도록 설득했고, 나머지는 역사입니다. 다음과 같은 기능이 있습니다. • 깔끔하고 직관적인 디자인 — 슬레이트를 사용하면 문서 왼쪽에 API에 대한 설명이, 오른쪽에는 모든 코드 예제가 있습니다. Stripe 및 PayPal의 API 문서에서 아이디어를 얻었습니다. 슬레이트는 반응형이므로 태블릿, 휴대전화, 인쇄물에서도 멋지게 표시됩니다. • 한 페이지에 모든 정보 표시 — 사용자가 원하는 정보를 찾기 위해 수백만 개의 페이지를 검색해야 했던 시대는 지났습니다. Slate에서는 전체 문서를 한 페이지에 표시합니다. 하지만 연결 가능성은 포기하지 않았습니다. 스크롤하면 브라우저의 해시가 가장 가까운 헤더로 업데이트되므로 문서의 특정 지점에 연결하는 것이 자연스럽고 쉽습니다. • 슬레이트는 단순히 마크다운입니다. 슬레이트로 문서를 작성할 때는 마크다운을 작성하기만 하면 되므로 쉽게 수정하고 이해할 수 있습니다. 모든 것이 마크다운으로 작성됩니다. 코드 샘플도 마크다운 코드 블록일 뿐입니다. • 여러 언어로 코드 샘플 작성 — API에 여러 프로그래밍 언어로 된 바인딩이 있는 경우 탭을 간단히 삽입하여 서로 전환할 수 있습니다. 문서에서 GitHub 맞춤형 마크다운과 마찬가지로 각 코드 블록 상단에 언어 이름을 지정하여 다양한 언어를 구별할 수 있습니다. • 100개 이상의 언어로 즉시 사용 가능한 구문 강조표시(구성이 필요하지 않음) • 페이지 맨 왼쪽에서 자동으로 원활하게 스크롤되는 목차 스크롤하면 문서 내 현재 위치가 표시됩니다. 속도도 빠릅니다. TripIt에서 Slate를 사용해 목차에 180개가 넘는 항목이 있는 새로운 API의 문서를 작성하고 있습니다. Google은 큰 문서에서도 뛰어난 성능을 유지합니다. • 사용자가 문서를 업데이트하도록 허용 — 기본적으로 슬레이트에서 생성된 문서는 공개 GitHub 저장소에 호스팅됩니다. 이렇게 하면 GitHub 페이지에서 문서를 무료로 호스팅할 수 있을 뿐만 아니라 다른 개발자가 오타나 다른 문제를 발견한 경우 문서에 대한 pull 요청을 쉽게 수행할 수 있습니다. 물론 GitHub을 사용하고 싶지 않다면 다른 곳에서 문서를 호스팅해도 됩니다. • RTL은 아랍어, 페르시아어 (페르시아어), 히브리어 등의 RTL 언어에 대해 완전한 오른쪽에서 왼쪽 레이아웃을 지원합니다. Verdict Slate는 문서를 생성하는 데 가장 강력한 오픈소스 소프트웨어 중 하나입니다. 저의 멘토인 Chris Myers와 함께 논의한 내용에 따라 4부에서는 슬레이트를, 다른 부분에서는 GitHub와 마크다운을 사용할 예정입니다. 문서에 관한 자세한 내용은 아래 섹션에서 설명합니다. 제안된 문서의 구조 2페이지에 있는 SynBioHub 사용자 가이드의 구조를 만들었습니다. 이 구조는 수락되며 Myers 씨에 의해 이미 수정되었습니다. 프로젝트 목표 1. 문서를 재구성합니다. 2. SynBioHub의 최신 버전에 맞게 문서를 업데이트합니다. 3. 사용하지 않는 정보를 삭제합니다. 4. 이해하기 쉽도록 사용자 문서를 다시 작성합니다. 5. 신규 참여자를 위해 SynBioHub의 기본 생물학적 개념과 인터페이스에 대한 기본적인 이해도를 높일 수 있도록 문서에 간략한 기본 요건 섹션을 포함합니다.