Веб-приложение часто содержит API для взаимодействия с ним. Документирование API позволит клиентам быстрее понять, как использовать ваши сервисы. Если API закрыт от внешнего мира, то все равно стоит уделить время спецификации — это поможет вашим новым коллегам быстрее разобраться с системой.
Создание документации вручную — утомительный процесс. Swagger поможет вам упростить эту работу.
Не только содержание, но и структура текста должна быть осмысленна.
Так, если мы говорим о техническом или научном тексте, например, о статье или документации, то форма должна помочь максимально быстро и легко понять содержание. Для меня, в случае статьи, это значит, что структура должна быть приблизительно такой:
Привет! У нас прошла конференция по разработке технической документации – ProКонтент 2019. Мне довелось изнутри посмотреть на процесс рождения конференции и даже выступить с пятиминутным мини-докладом. Не претендуя на объективность, очень кратко расскажу про доклады, которые мне больше всего понравились.
Читать полностью »
Писал комментарий к статье и понял, что надо выносить в отдельный пост.
Как многие отмечают там в комментариях статья отстой, человек не разбирается и смешал всё в кучу, попробую поделиться своими выводами от использования разных разметок.
Читать полностью »
В прошлый раз мы говорили о разнице между login и log in. В продолжение темы — ещё несколько нюансов, о которых вы просили рассказать в комментариях.
‘Login’ или ‘log in’? Одно слово или два? Это достаточно распространенный вопрос среди тех, кто пишет на английском языке. Давайте разберемся, как же правильно.
О RAML — языке разметки, используемом для описания RESTful API, мы уже писали. В обсуждении статьи на Хабрахабре один из читателей заметил, что RAML уже давно не обновляется, чуть ли не с лета 2014 года.
Несколько месяцев формат RAML был существенно усовершенствован. Новая спецификация версии 1.0 была опубликована на официальном сайте относительно недавно, в начале октября 2015 года. По сравнению с предыдущей версией (0.8) в неё было внесено много изменений и дополнений. О наиболее значительных нововведениях мы подробно расскажем в этой статье.
Читать полностью »
Работая над проектами связанными с авионикой мне потребовалось оформить несколько комплектов документации с полным описанием проекта. Также следовало учитывать требования многих ГОСТов на оформление и на содержание документации, таких как ЕСПД, КТ-178B и других.
Описание должно было в себя включать:
Объем документирования очень большой. Данные во всех документах связаны друг с другом, поэтому при изменении проекта (например добавления нового требования), приходится редактировать практически все документы. Плюс к этому можно где-то ошибиться или забыть поправить, что приводит к ошибкам в документации.
Далее в статье я расскажу как я решил эту проблему.
Недавно мной была написана статья, посвященная системе документации Doxygen (если вы не знакомы с данной системой, то советую обратить внимание на указанную статью и познакомиться с ней хотя бы в общих чертах). В комментариях к ней был поднят важный вопрос об оформлении документации в Doxygen, и этот вопрос актуален, поскольку зачастую используется стандартное оформление, которое хоть и практичное, но достаточно невзрачное.
В данной статье я отвечу на этот вопрос. Для этого мы рассмотрим общие принципы оформления документации Doxygen, познакомимся с ними, и посмотрим на примерах, чего можно добиться, основываясь на них.
Читать полностью »
Quick Help для своего кода в XCode 5
2013-09-03 в 3:55, admin, рубрики: comments, documentation, doxygen, iOS, mac os x, objective-c, xcode, документирование, комментарии, разработка под iOS, метки: comments, documentation, doxygen, iOS, mac os x, objective-c, xcode, документирование, комментарииQuick Help научился брать документацию из комментариев:
Читать полностью »