В каком формате лучше всего писать документацию к API?

Question

[Алексей]

Добрый день!
Написали документацию по API, возник вопрос насколько документация понятна. Помогите разобраться с этим вопросом. Вот документация https://2polyglot.com/api/ . Подскажите, в каком формате лучше всего писать документацию к API?

Answer 1

[Александр Аксентьев]

Все красиво-хорошо, но нужен поиск хотя бы по названиями функций.
И категории, там же все разбито блоками, но в меню один уровень.
Категории свернутые по умолчанию, чтобы очень быстро найти нужную функцию, даже без поиска.

Ну и зачем вообще документация на русском :)
Там более там встречаются английские слова, выберите что-то одно. А то идет через строчку рус/англ: dsro.ru/gyazo/images/69aedddce842039de0fa83223b12.png

Answer 2

[Дмитрий Вапельник]

очень советую обратить внимание на raml.org
из этого дела очень даже неплохо и красиво генерируется документация к API