Comments 17
Стандартом отрасли для технической документации давно является markdown
А может AsciiDoc?
Не увидели каких-то серьезных преимуществ у AsciiDoc, как формата. По большому счету, ключевая разница только в наличии ряда расширенных блоков форматирования типа многострочных ячеек в таблице. Но в Diplodoc это все решается рядом плагинов https://diplodoc.com/docs/ru/syntax/ Тут и таблицы, и сноски и всё остальное. И markdown знает практически любой разработчик, который хоть раз дело с гитхаб имел, а AsciiDoc - отдельная история
это все решается рядом плагинов
Тут и таблицы, и сноски и всё остальное
И markdown знает практически любой разработчик
Вы не чувствуете противоречия? Вы ставите кучу плагинов, а потом аппелируете к тому что практически любой разработчик это знает. Откуда? Практически любой разработчик пользуется diplodoc и знаком со спецификой его плагинов?
Преимущество AsciiDoc'а как раз в гораздо большем объёме штатной функциональности.
так эти плагины нужны нашей команде документации для специфического оформления. ни один из внутренних разработчиков ничем таки не пользовался. они дают базовое описание в формате, который точно знают. не надо объяснять, как заголовок сделать или ссылку. а это 95% всего, что от них ждут. а кто из них видел AsciiDoc?
Речь же не о том, что AsciiDoc лучше или хуже. Он стопудово менее распространенный, чем markdown, вот и все. Возможно, завтра это изменится, но пока это так. И на текущий момент и с нашими текущими потребностями гораздо эффективнее расширить известный стандарт в паре мест для специфических блоков оформления, чем полностью менять стандарт на другой. Кстати, даже слово "нашими" я выделил сейчас здесь на хабре с помощью разметки markdown. Телега прекрасно сообщения в markdown принимает...
Возможно, "завтра" мы решим перейти на AsciiDoc, если столкнемся с необходимостью достичь новых целей, которые с markdown в каких-то ключевых вещах несовместимы. Точно так же, как мы перешли на Diplodoc с его markdown/yaml вместо html в старой нашей документации. Я вроде целую статью написал, почему мы к такому решению пришли.
"Сегодня" для наших целей AsciiDoc не дает ни одного заметного преимущества в сравнении с markdown.
В общем, я не пойму, о чем мы тут спорим, на самом деле. Самое главное в нашей истории не markdown, а Documentation as Code. Вам нравится AsciiDoc как формат больше - флаг вам в руки! Правда. Это такая мелочь, как заголовок обозначать - ## или ==, важно же совсем другое.
Както год назад понадобилось мне чтото из апи битрикса24. Зашел на сайт документации. Оформление ужасное, примеры то есть то их нет, описание из пары строк и тд. Это худшее что я видел. Так что я просто не верю что челы с таким бакграундом внезапно поменялись
Отличная статья, только один вопрос, а существует ли поиск по базе документации? Например, если я хочу просто найти откуда пришёл атрибут по его названию?
у нас есть чек-лист из 20 пунктов, который обязательно должен быть пройден при получении заготовки от разработчиков.
Можете поделиться чек-листом?
К сожалению, нет - это внутренний документ и там половина внутренней кухни. но мы на его основе соберем публичный гайд, включим в репозиторий для внешних контрибьюторов
могу выдержкой поделиться
1. если в параметрах встречается поле с идентификатором связанного объекта (например, responsibleId - ответственный за сделку пользователь и т.п.), то в описании параметра необходимо давать ссылку на метод, которым можно получить такой идентификатор. Правильнее всего давать ссылку на соответствующий списочный метод вроде crm.lead.list, user.get и т.п.
тоже самое касается и полей со значениями из какого-то справочника. например, справочник типов crm-обхектов. или справочник статусов сделки и т.д. если мы ссылаемся на что-то - надо указывать метод, которым можно вытащить значение и, возможно, указать, как формировать условие для получения нужных значений с помощью этого метода. например, справочник может быть большой для разного типа объектов (так происходит, в частности, со справочником всевозможных статусов в crm). надо подсказывать, как в методе *.list выбрать из справочника только значения нужного типа.
2. если параметр представляет собой массив полей (чаще всего в методах add/update), то либо надо описывать конкретные поля, входящие в состав массива в отдельной таблице на этой же странице, либо делать специальный "тип данных" и выносить эти поля на страницу с типами данных внутри. Может быть вариант, что таблица таких параметров описана на странице метода add, тогда на странице типа update можно сослаться на эту таблицу с помощью ссылки с позиционированием на конкретный блок. Но нельзя делать описания типа "поля соответствуют полям метода *.fields", потому что они точно не соответствуют - структура ответа у методов типа *fields не соответствует структуре параметра в методах вида add/update. это только путаницу вносит.
3. тип параметра array может быть только в случае параметра, который принимает значения вида [xxx, yyy, zzz]. если параметр принимает значение вида [xxx: yyy, bbb: ccc], то это параметр типа object или конкретного особого типа (например, sale_order), вынесенного в таблицу типов внутри раздела документации.
4. нужно наличие всех положенных блоков
5. блок ошибок в идеале должен содержать два столбца:
символьно-числовой код ошибки (error)
разъяснение ошибки на русском
бывает, что разработчики не делают отличающиеся символьно-числовые коды ошибок, а различают ошибки по error_description. тогда в таблице описания должны быть три столбца:
символьно-числовой код ошибки (error)
сообщение об ошибке (error_description)
разъяснение ошибки на русском
однако, бывает, что error_description выдается локализованный на русском языке или английском. тогда в таблице описания должно быть 4 столбца:
символьно-числовой код ошибки (error)
сообщение об ошибке на русском (error_description ru)
сообщение об ошибке на английском (error_description en)
разъяснение ошибки на русском
разработчикам это понадобится, потому что они в своем коде будут привязываться к error_description
6. В примерах кода надо давать максимально доступный перечень параметров у метода. А то бывает, что метод принимает 2 десятка параметров, а в примере показывают только ID, TITLE. Это плохая практика, потому что как раз особенности хорошо видны не в базовых полях, а во всех прочих. Особенно важно это в случае, если параметр представляет собой массив (как, например, PHONE в параметре FIELDS при добавлении лида и т.п.) или файл.
7. если какие-то параметры имеют особенности при формировании значений, то эти особенности надо описывать в таблице параметров, а не в виде комментариев в примере. дело в том, что комментарии в примере будут утеряны при конвертации примера в вызов curl. А значит, читатель может ничего про особенность не прочитать, если не будет смотреть пример на js/php. Поэтому лучше все писать в описаниях в таблице параметров
...
Можно ли реализовать автоматическую генерацию схем в формате OpenAPI, таких как YAML или JSON? Это может значительно упростить восприятие и использование документации в различных инструментах автоматизации
Для автоматической генерации нужно соответствующее "ядро" для REST API внутри продукта. Текущая версия REST, увы, не позволяет нам это сделать. В требования к новой версии, которая в разработке, заложена поддержка OpenAPI. На мой взгляд, это не решит всех вопросов, потому что в сложной системе описания "протоколов" в виде параметров методов всё равно не всегда делает картину взаимодействия между сложноподчиненными объектами понятной. Но, безусловно, это как минимум упростит знакомство с API, так что мы в эту сторону идём
Ваша дока лагает как припадошная.
https://disk.yandex.ru/i/HDWjO8YHbP8Nvg
Это я просто открыл и потыкал пару разделов. Про то что саму доку писал кто-то, мягко говоря, не особенно внимательный, я вообще молчу.
Вы банально её просто не лагающей сделать не вывезли.
Не понимаю как вам не стыдно за этот, кхм... "продукт" денег брать.
Documentation as Code: как мы создали новую версию документации для Rest API