Рубрика «документация»

Почему некоторыми API удобнее пользоваться, чем другими? Что мы как фронтендеры можем сделать на своей стороне, чтобы работать с API приемлемого качества? Сегодня я расскажу читателям Хабра как о технических вариантах, так и об организационных мерах, которые помогут фронтендерам и бэкендерам найти общий язык и наладить эффективную работу.

Бэкенд для фронтенда, или Как в Яндекс.Маркете создают API без костылей - 1

Этой осенью Яндекс.Маркету исполняется 18 лет. Все это время развивается партнерский интерфейс Маркета. Если кратко, то это админка, с помощью которой магазины могут загружать каталоги, работать с ассортиментом, следить за статистикой, отвечать на отзывы и т.д. Специфика проекта такова, что приходится очень много взаимодействовать с различными бэкендами. При этом данные не всегда можно получить в одном месте, из одного конкретного бэкенда.

Читать полностью »

Пишем техническую документацию: руководство для непрофессионала - 1

Осенью 2016 года нам с коллегой поручили улучшить документацию и контент в моей бывшей компании. Мы потратили год на все виды документации: справочник по API, руководства, учебные пособия, сообщения в блогах. До этого я 5 лет писала доки, но официально не обучалась этому. Но и неопытной меня нельзя назвать: кроме документирования API для проектов и стартапа, я ещё преподавала Python Flask на семинарах во время учёбы на последних курсах в университете. Но сейчас выпала возможность сосредоточиться только на любимом деле: помогать специалистам всех уровней через техническую документацию.

В этом году я многому научилась в сообществе Write The Docs, у других провайдеров API, а также методом проб и ошибок. В прошлом году я поделилась опытом в докладе «Что мне хотелось бы знать о написании документации» на конференции API Strategy and Practice в Портленде. Эта статья — обзор полученных знаний.
Читать полностью »

Преамбула

Для того, чтоб описать и задокументировать правила клиент-серверного
взаимодействия используя Rest-api можно выделить три основных метода:

  1. Описывать своим коллегам правила обращения к серверу на пальцах
    Этот метод быстр и не требует долгосрочной поддержки, но высока вероятность, что вас за это будут бить.
    Система автоматического документирования REST-API в Laravel проектах - 1
  2. Руками составлять Google-docs/Wiki/Readme в проекте
    Удобно тем, что однажды написанная документация не требует повторного объяснения. Её можно показать коллегам и даже иногда заказчику. Минусом данного метода является долгосрочная поддержка такой документации. Когда Api в проекте вырастает до таких размеров, что сама мысль "А когда же я обновлял документацию?" вызывает холодок по спине, тогда вы понимаете, что дальше так продолжаться не может. Формально вы можете обновлять документацию очень часто и маленькими фиксами, но это до первого отпуска.
  3. Использовать систему автодокументирования
    И вот для того, чтобы решить минусы первых двух методов человечество придумало системы автоматического документирования. Основная идея заключается в том, что к проекту пристыковывается некий плагин, который собирает информацию по вашему коду, сам составляет документацию и обёртывает её в удобочитаемый формат. Но большинство решений по этому методу не идеальны. Давайте попробуем сделать инструмент, который поможет получить документацию нашего проекта с минимальным количеством телодвижений

    Читать полностью »

Пост в продолжение темы экспериментальных решений (https://habrahabr.ru/post/350382/), откуда будет переиспользован код для примера. В прошлом посте я затронул тему, как можно написать тесты на простой сервис, когда он выступает в роли черного ящика и из кода теста у нас нет прямого доступа к коду тестируемой программы. Ещё раз остановлюсь на том, что тестируемый сервис был реализован на языке Go, а тесты к сервису на языке Ruby и фрэймворке для тестирования RSpec. Стэк был выбран из собственных предпочтений и не имеет ключевого значения к рассматриваемой теме. В этой статье хочу рассмотреть вопрос документирования API, вновь используя не совсем стандартное решение.
Читать полностью »

Во фронтенде практически безраздельно правит OpenSource, а с недавних пор набирает популярность компонентный подход. Вроде бы всё чудесно. Небольшим компаниям компонентный подход помогает переиспользовать код, а крупным компаниям выравнивать UX во всей линейке продуктов, сервисов и прочего. И вот мы все такие замечательные крутые разработчики пилим свои фреймворки, библиотеки и виджеты, радостно полагая, что если они решают наши задачи, то решают и проблемы окружающего мира. Мы выкладываем их в паблик, ожидая благодарных пользователей, звезд на GitHub, скачиваний на NPM-е. Но почему-то одни библиотеки взлетают, а другие остаются незамеченными и позабытыми.

Как сделать Public API, которым будут пользоваться - 1

Читать полностью »

При разработке документации мы руководствуемся не только стандартами, но и удобством её использования. Стандарты определяют состав и форму документации, а формат строится исходя из удобства. Разработчик Сергей Бочаров рассказывает о пути Markdown-документа и о проблемах, которые приходится решать в обмен на простоту использования этого формата.

У меня иногда складывается впечатление, что не он служит для нас, а мы служим для этого формата. Поэтому — сэр Markdown.

Читать полностью »

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

Читать полностью »

С тех пор как я перешел к работе над крупными, комплексными проектами, я продолжаю утверждаться в том что есть два типа программистов – назовем их логики и визуалы.

  • Логики – это программисты с классическим флёром. Чтобы познакомиться с новой технологией они идут и читают документацию. Четкость кода – повышенная, ни шага влево, ни шага вправо. От забора и до обеда. Непритязательность к удобству работы с кодом пугает – кажется, что они могут работать и с минифицированным кодом, пользуясь одной только функцией поиска.
  • Визуалы – это люди, подходящие к коду более творчески, абстрактно. Чтобы изучить технологию они идут в youtube и смотрят видео про дельфинов уроки. В коде им важно разделение на осязаемые блоки, отсутствие простыней на 1000+ строк, возможность реализовать по-новому. Выполняя новую задачу они будут пристреливаться и искать свой вариант решения вместо поисков уже имеющегося на просторах интернета.

Речь в этой статье пойдет об инструменте разработки, без которого я, как представитель второго типа, уже не мыслю разработку проектов размером больше 250 строк и который, я уверен, будет полезен нашим коллегам из классического типа – он сделан в сотрудничестве с одним из вас – восходящей звездой мира программирования Степаном! Итак!
Читать полностью »

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

В этой статье я, технический писатель Renga Software Анастасия Тян, расскажу, от чего мы отталкивались в начале разработки справки для BIM-системы Renga и к чему в итоге пришли.

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

Как мы делаем справку для Renga - 1

С самого начала разработки Renga было понятно, что нам необходима современная онлайн-справка. Также было принято решение, что мы не будем отказываться от оффлайн-справки в формате CHM, чтобы пользователи могли к ней обращаться без подключения к интернету и не тонуть в ворохе html-файлов.Читать полностью »

Привет! Предлагаю вашему вниманию свободный перевод статьи «Good code is its own best documentation» от Amit Shekhar.

image

Хороший код, как хорошая шутка — не требует объяснений.
Читать полностью »