mirror of
https://github.com/twirl/The-API-Book.git
synced 2025-03-17 20:42:26 +02:00
style fix
This commit is contained in:
parent
a019579ee9
commit
db55d255ab
@ -1,6 +1,6 @@
|
||||
К сожалению, многие провайдеры API уделяют справочной документации прискорбно мало внимания; между тем документация является ни много ни мало лицом продукта и точкой входа в него. Проблема усугубляется тем, что написать хотя бы удовлетворительную с точки зрения разработчиков документацию невероятно сложно.
|
||||
К сожалению, многие разработчики API уделяют справочной документации прискорбно мало внимания; между тем документация является ни много ни мало лицом продукта и точкой входа в него. Проблема усугубляется тем, что написать хотя бы удовлетворительную с точки зрения разработчиков документацию невероятно сложно.
|
||||
|
||||
Прежде, чем мы перейдём к описанию видов и форматов документации, хотелось бы проговорить очень важную мысль: разработчики взаимодействуют со справкой по вашему API совершенно не так, как вы себе это представляете. Вспомните, как вы сами работаете надо проектом: вы выполняете вполне конкретные шаги.
|
||||
Прежде, чем мы перейдём к описанию видов и форматов документации, хотелось бы проговорить очень важную мысль: пользователи взаимодействуют со справкой по вашему API совершенно не так, как вы себе это представляете. Вспомните, как вы сами работаете надо проектом: вы выполняете вполне конкретные шаги.
|
||||
1. Необходимо установить (чем быстрее, тем лучше!) подходит ли в принципе данный сервис для вашего проекта.
|
||||
2. Если да, то нужно найти, как с его помощью решить конкретную задачу.
|
||||
|
||||
@ -40,7 +40,7 @@
|
||||
|
||||
Под руководством мы понимаем специально написанный человекочитаемый текст, в котором изложены основные принципы работы с API. Руководство, таким образом, занимает промежуточную позицию между справочником и примерами: подразумевает более глубокое, нежели просто копирование кусков кода из примеров, погружение в API, но требует меньших инвестиций времени и внимания, нежели чтение полного референса.
|
||||
|
||||
Руководство должно в связном и логичном виде излагать концепции API раздел за разделом; по смыслу руководство — это такая «книга», в которой вы доносите до читателя, как работать с вашим API. Правильно составленное руководство, таким образом, должно примерно следовать принципам написания книг по программированию, т.е. излагать концепции последовательно от простых к сложным. Кроме того, в руководстве должны быть зафиксированы:
|
||||
По смыслу руководство — это такая «книга», в которой вы доносите до читателя, как работать с вашим API. Правильно составленное руководство, таким образом, должно примерно следовать принципам написания книг по программированию, т.е. излагать концепции консистентно и последовательно от простых к сложным. Кроме того, в руководстве должны быть зафиксированы:
|
||||
* общие сведения по предметной области; например, для картографических API руководство должно содержать вводную часть про координаты и работу с ними;
|
||||
* правильные сценарии использования, т.е. «happy path» API;
|
||||
* описания корректной реакции на те или иные ошибки;
|
||||
@ -58,7 +58,7 @@
|
||||
|
||||
##### Офлайн-документация
|
||||
|
||||
Хотя мы и живём в мире победившего онлайна, офлайн-версия документации в виде сгенерированного документа, тем не менее, бывает полезной — в первую очередь как «снапшот» актуального состояния API на определённый момент времени.
|
||||
Хотя мы и живём в мире победившего онлайна, офлайн-версия документации в виде сгенерированного документа, тем не менее, бывает полезной — в первую очередь как «слепок» актуального состояния API на определённый момент времени.
|
||||
|
||||
#### Проблемы дублирования контента
|
||||
|
||||
@ -67,12 +67,12 @@
|
||||
* явное и заметное указание на существование более актуальной версии страницы для новых API;
|
||||
* пессимизация (вплоть до запрета индексирования) документации к устаревшим версиям API.
|
||||
|
||||
Если вы поддерживаете обратную совместимость, то можно попытаться поддерживать единую документацию для всех версий API. В этом случае для каждого метода нужно указывать, начиная с какой версии API появилась его поддержка. Здесь, однако, возникает проблема с тем, что получить документацию для какой-то конкретной (устаревшей) версии API (и вообще понять, какие возможности предоставляла определённая версия API) крайне затруднительно. (Но с этим может помочь офлайн-документация, о чём мы упоминали выше.)
|
||||
Если вы поддерживаете обратную совместимость, то можно попытаться поддерживать единую документацию для всех версий API. В этом случае для каждой сущности нужно указывать, начиная с какой версии API появилась её поддержка. Здесь, однако, возникает проблема с тем, что получить документацию для какой-то конкретной (устаревшей) версии API (и вообще понять, какие возможности предоставляла определённая версия API) крайне затруднительно. (Но с этим может помочь офлайн-документация, о чём мы упоминали выше.)
|
||||
|
||||
Проблема осложняется, если вы поддерживаете документацию не только для разных версий API, но и для разных сред / платформ / языков программирования — скажем, ваша визуальная библиотека поддерживает и Android, и iOS. В этой ситуации обе версии документации полностью равноправны, и выделить одну из них в ущерб другой невозможно.
|
||||
|
||||
В этом случае необходимо выбрать одну из двух стратегий:
|
||||
* если контент справки полностью идентичен для всех платформ, т.е. меняется только синтаксис кода — придётся подготовить возможность писать документацию обобщённым образом, подходящим под все платформы, и дать опцию динамически менять выбранную платформу;
|
||||
* если контент справки полностью идентичен для всех платформ, т.е. меняется только синтаксис кода — придётся подготовить возможность писать документацию обобщённым образом: статьи документации должны содержать примеры кода (и, возможно, какие-то примечания) сразу для всех поддерживаемых платформ;
|
||||
* если контент, напротив, существенно различен (как в упомянутом кейсе Android/iOS), мы можем только предложить максимально разнести площадки, вплоть до заведения разных сайтов: хорошая новость состоит в том, что разработчикам практически всегда нужна только одна из версий, другая платформа их совершенно не интересует.
|
||||
|
||||
#### Была ли эта статья полезна для вас?
|
||||
|
Loading…
x
Reference in New Issue
Block a user