웹 서비스를위한 문서 표준/구조/스타일 [폐쇄

Question

누구든지 웹 서비스의 고급 문서화에 대한 지침을 추천 할 수 있습니까?

이것은 특정 웹 서비스에 대한 지식이없는 사람이 존재의 이유, 로드맵 및 사용의 예에 대한 기본적인 이해를 가져 오도록 허용하는 문서입니다.

이러한 문서는 A4/Letter Paper의 두 개의 인쇄 된 측면에 적합하고 10 분도 채 걸리지 않아야합니다.

이는 개발자가 인터페이스를 소비하는 데 사용할 수있는 저수준 API 문서를 보충합니다.

Answer 1

가이드 라인이 있는지 확실하지 않지만 웹 서비스 API를위한 좋은 문서 세트 인 것으로 밝혀진 예를 보여줄 수 있습니다.

http://www.flickr.com/services/api/

Flickr API 페이지는 매우 읽기 쉬운 형태로 설정됩니다. 이 페이지는 기본적으로 다음과 같습니다.

• 개요 페이지 링크
• 일반적인 시나리오 쓰기 (이 인스턴스의 사진 업로드)
• API를 소비하는 도구에 대한 정보
• 활동별로 그룹화 된 각 API 방법의 자세한 설명

특히, 일반적인 액세스가 Paterns (사진 업로드, 사진 교체)를 설명하는 페이지는 나에게 중요합니다. 그들은 API의 소비자에게 일반적인 일을하는 방법과 사람들이 API를 사용할 것으로 기대하는 방법을 보여줍니다. 마지막 요점은 중요합니다. "이봐, 우리는 이러한 종류의 오류 처리로 이러한 방법을 사용하여 이와 같이 우리를 부를 것으로 기대합니다"라고 말하고 싶습니다. API 사용법에 대한 모범 사례를 사용자에게 보여 주면 많은 지원 통화를 절약 할 수 있습니다.