이 페이지에는 Google Season of Docs에서 승인된 테크니컬 라이팅 프로젝트의 세부정보가 포함되어 있습니다.
프로젝트 요약
- 오픈소스 조직:
- OpenMRS.org
- 테크니컬 라이터:
- batbrain7
- 프로젝트 이름:
- OpenMRS REST API 문서
- 프로젝트 기간:
- 표준 기간 (3개월)
Project description
제안서를 여러 섹션으로 나누고 Google 지도 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주간의 문서 작성 기간 동안 완료된 작업에 대한 최종 보고서를 준비하겠습니다. 또한 문서 검토 및 마무리 작업에도 시간을 할애하겠습니다.