이 페이지에는 Google Season of Docs에서 수락된 기술 작문 프로젝트의 세부정보가 포함되어 있습니다.
프로젝트 요약
- 오픈소스 조직:
- OpenMRS.org
- 테크니컬 라이터:
- batbrain7
- 프로젝트 이름:
- OpenMRS REST API 문서
- 프로젝트 기간:
- 표준 기간 (3개월)
Project description
제안서를 여러 섹션으로 나누어 Google Maps API 문서와 GitHub API 문서 등의 흐름을 따를 것입니다.
이와 별도로 realworld.io에서 작성된 API 문서의 리드미 구조(https://github.com/gothinkster/realworld/tree/master/api)를 제안합니다.
개인적으로 이 문서가 매우 이해하기 쉽고 사용하기 쉬웠습니다.
제안서는 주로 다음 3가지 섹션으로 구성됩니다.
API, OpenMRS, API 사용 방법 및 이후의 내용에 대한 간단한 소개를 제공하는 섹션.
API 키를 얻는 방법 및 API 요청을 하는 데 일반적으로 필요한 인증 여기에는 API에 있는 인증 유형의 샘플 예시, API에 존재해야 하는 키와 값, 해당 부분의 키에 따라 허용되는 값 유형이 포함됩니다. 언어에 상관없이 코드 샘플은 API에서 헤더와 응답 형식, 기타 쿼리 매개변수를 작성하는 방법을 지원합니다.
API에서 가져오는 응답 유형, JSON 유형 또는 API에서 반환하는 다른 유형의 결과를 언급해야 합니다.
다양한 API 경로와 함께 헤더 및 기타 항목과 함께 전송해야 하는 모든 매개변수 각 API는 코드를 작성하는 동안 요청이 이루어지는 방식을 설명하는 몇 가지 언어로 된 코드 샘플의 지원을 받습니다. 각 API에서 발생할 수 있는 일반적인 오류 코드도 언급해야 합니다.
이는 REST API에 대해 문서를 정의하는 방법에 대한 일반적인 개념입니다.
프로젝트 일정은 다음과 같습니다.
8월 1일~9월 1일
제 멘토를 만나고 코드베이스의 여러 부분에서 필요한 문서 수준에 대해 심도 있게 논의하고, 저수준 및 고수준 문서를 어떻게 심층적으로 다루어야 하는지도 논의합니다. 또한 이 시간을 통해 코드베이스를 이해하고 개념을 더 잘 문서화할 수 있도록 개념을 연구할 것입니다.
1주 차와 2주차
재능기부자 가이드를 업데이트하고 확장하겠습니다. 소스 코드를 빌드하는 방법에 대한 문서를 개선하겠습니다. 또한 새로운 기여자가 문서에 어떤 도움을 줄 수 있는지 설명하는 문서 자료 섹션도 추가합니다. 다양한 API 문서를 학습하고 소개부터 시작하여 API 인증을 추가합니다.
3~8주 차
API 경로 및 응답을 각 API 유형에 대한 코드 샘플과 함께 추가하겠습니다 (유사한 API 유형이 있을 수 있음).
9~10주 차
링크를 사용하여 API 문서 구조화(예: 긴 API 문서의 연결된 색인)를 추가하고 코드 섹션, 개요, 매개변수, 루트 엔드포인트와 같은 다른 기준으로 더 나눕니다.
마지막 주
마지막 주에 12주간의 문서 작성 기간 동안 완료된 작업에 대한 최종 보고서를 준비할 것입니다. 문서를 검토하고 마무리하는 데도 시간을 할애하겠습니다.