Семь навыков, необходимых для написания документации по API…

Семь навыков, необходимых для написания документации по API…

Это вы можете использовать прямо сейчас ... чтобы выполнять свою работу ... лучше и быстрее.

Написание документации по API - это неправильно понимаемое сообщество. От генеральных директоров до даже менеджеров по написанию технических текстов - немногие понимают, что он должен делать, и еще меньше понимают, как это делать. И в этом-то и проблема. Вы не можете поступить в колледж, чтобы получить степень по написанию документации по API, здесь мало сертификатов, а обучение на рабочем месте минимально. Это больше похоже на подход «тонуть или плыть», когда людей бросают в роль и ждут, что они поймут это по ходу дела. Ничто из этого не делает хорошего плана документации.

Итак, как получить работу - это отдельная тема, и ее нужно рассматривать отдельно. Однако есть базовые навыки, которые вы можете освоить сейчас, которые применимы непосредственно к написанию документации по API. У этих навыков есть четыре общих момента.

• Они будут использоваться при написании документации API. Привыкайте к ним сейчас. Каждый инструмент, конечно, будет немного отличаться, но привыкните к их формату, обозначениям и стилю сейчас, когда вы не находитесь под давлением. Попав в эту должность, вам нужно будет многому научиться.
• Это навыки, которые вы можете использовать прямо сейчас. Вы можете подумать, что они бесполезны, или вы можете подумать, что вам не нужны другие инструменты. Это опасно узкое мышление. Вы не собираетесь использовать один инструмент. Во-первых, набор инструментов для составителя документации API можно назвать в лучшем случае слабым, а в худшем - неадекватным. Подумайте о том, чтобы использовать целый ряд инструментов, и начните использовать их прямо сейчас.
• Изучите ожидания, а не требования. Слишком часто компании предъявляют требования к позиции или продукту. Хотя требования имеют свое место, они, как правило, отпугивают людей, поскольку не соответствуют требованиям или искажают продукт. Вы можете удовлетворить требования, но при этом не сделать нужный продукт. Это все равно, что смотреть на суши только как на сырую рыбу. Это технически правильно, но совершенно не соответствует впечатлениям. Однако если вы оправдываете ожидания программистов и они довольны тем, что им дают, вы создали правильный продукт. К черту требования.
• Изучите теорию. После этого все остается лишь деталью реализации. Изучите концепции того, как и почему что-то работает, вы всегда можете узнать, как это сделать. Например…
  1. Если вы изучаете цикл на одном языке, вы знаете, что цикл будет поддерживаться и на других языках. Вам не нужно спрашивать, есть ли в другом языке петли. Вы можете сослаться на синтаксис.
  2. В другом примере пользователи Madcap Flare понимают, как работает Flare. Если вы используете Flare из коробки, вы получите отличные результаты, потому что это отличный продукт. Однако, если вы изучите HTML, вы откроете уровень HTML для своих изменений. Это расширяет ваши возможности. Изучите XML, и вы сможете сделать даже больше, поскольку на самом низком уровне Flare использует те же файлы XML, которые вы можете изменять. Еще один шаг - и вы узнаете, что XML и HTML - это просто текстовые файлы, и вы откроете свой проект для каждого инструмента на рынке, который изменяет простые текстовые файлы. Если вам не нравится проверка орфографии в Flare, вы можете использовать другую проверку орфографии, чтобы воздействовать непосредственно на файлы XML или HTML в проекте Flare. Дело в том, что у вас будет так много дополнительных опций и так много дополнительных инструментов.

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

Что такое API? API - это набор команд, понятных приложению или серверу. Например, когда вы покупаете принтер, он поставляется со своим собственным набором команд. Приложение, такое как Microsoft Word, должно отправлять точные команды печати, чтобы принтер мог их понять. Аналогичным образом, при использовании браузера для поиска на Amazon точный набор команд, включая, возможно, параметры поиска, должен быть отправлен на серверы Amazon.

Зачем нужна документация? Просто: их звонки не обнаруживаются. То есть сами программисты никак не смогут вычислить или обнаружить набор вызовов. Даже если бы они могли, все равно есть параметры, предостережения, предупреждения и другие примечания, которые требуют объяснения. Короче говоря, программисту нужно сказать, что это за команды. Говорят, это документация.

Следовательно, по сути, документация - это приложение.

Если вы планируете перейти к написанию документации по API или думаете, что, возможно, захотите перейти к этому позже, вот несколько важных навыков. Даже если вы не планируете писать документацию по API, это просто полезные навыки. Вы можете использовать любой из них или их комбинацию по своему усмотрению.

# 1 Выучить код

Написание документации по API - это писать программистам о программировании. Вам нужно знать программирование. Почему могло быть иначе? Но изучение кода может происходить по иным причинам, чем вы думаете.

Изучите компьютерный язык. Есть много сайтов и статей, в которых обсуждают, какой язык является лучшим. Не путайте: это не имеет значения. 80% всех языков являются общими. Если вы изучаете Basic, то Java, JavaScript или C # - это просто модификации Basic. Это часть темы. Изучите теорию, и все остальное станет на свои места. После этого реализация - это просто детали, которые вы можете найти.

Кроме того, это даже не обязательно язык. Это могут быть сценарии, макросы или даже инструменты автоматизации. Подробнее об этом позже. Выбор языков на самом деле не имеет значения, хотя может облегчить жизнь. Если вы работаете над веб-проектом, вам могут подойти Java и JavaScript. Компьютерное приложение, тогда .NET вроде C # - это хорошо. В любом случае Python занимает достойное второе место благодаря своей универсальности.

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

Знание языка заставляет сочувствовать пользователям. Вы знаете то, что знают они, и знаете, с какими проблемами они сталкиваются. Но для нас недостаточно просто посочувствовать пользователям. Нам нужно сопереживать им. Читать дальше.

# 2 Узнайте об изучении кода

При изучении языка одним из факторов является изучение языка. Это означает, как вы получаете информацию и как лучше ее сохранить? Среда - это документация API. У них есть звонки, о которых они хотят, чтобы вы знали, и они представляют их так, как считают нужным. Вопрос только в том, согласны ли вы. Во время этого процесса особенно внимательно относитесь к тому, как вы получаете информацию, и что вам нравится и не нравится в каждом подходе. Речь идет не о книгах и видео, хотя этот аспект есть. Речь идет о каждом шаге. Какие методы были наиболее эффективными? Наименее эффективный?

Теперь вы сочувствуете пользователю. Вы находитесь там же, где и они, для обучения. То, что вам не понравилось, им не понравится. И наоборот, то, что вам понравилось, тоже понравится. Развивайте свои собственные стили. Избегайте одних вещей, продолжайте использовать другие и во всех случаях улучшайте то, что вы видели. Могут быть подходы, которые вам не нравятся, но в них есть небольшие аспекты, которые вам понравились. Возьмите все эти кейсы и измените их, чтобы они стали вашими. Но вы бы никогда не попали сюда, если бы не выучили язык.

# 3 Научитесь использовать код

Лучший способ выучить язык - это использовать его. Я сказал ранее, что это «навыки, которые вы можете начать использовать прямо сейчас». Найдите занятия, которые позволят вам выполнять свою работу. Это сохранит ваш интерес, даст вам что-то полезное и подтолкнет к более глубокому изучению языка.

Если вы изучаете язык, напишите программу, которая изменяет выбранный текст на все строчные буквы. Эта программа должна состоять примерно из четырех строк. Когда я работал с Flare, у меня было приложение, которое меняло текст на нижний регистр и заменяло пробелы символами подчеркивания. Я использовал это для создания привязок для HTML. Затем я сделал еще один шаг и попросил приложение создать как тег привязки, так и тег ссылки. После этого нужно было скопировать и вставить, чтобы использовать два тега.

Языки - не единственные варианты. Также есть макросы и языки сценариев. Оба они позволяют автоматизировать инструмент, написав сценарии, а затем запустив их позже. DOS все еще существует. Фактически, есть вещи, которые вы можете делать только в DOS, но не через поисковик Windows. Предположим, например, что у вас есть сложная процедура, например, для архивирования файлов после проекта. Вам нужно скопировать файлы из нескольких папок в одну, переименовать их и заархивировать все в один файл. Вы можете сделать это из командной строки. Но вместо того, чтобы делать это пятью отдельными командами, их можно объединить в одну команду.

Это широко используется в сообществе разработчиков документации по API, так что это необходимый навык. Независимо от того, Windows или Linux, вы можете использовать его прямо сейчас. Каждое из следующих приложений имеет возможность создания сценариев или макросов.

• Windows: командные файлы, командная строка.
• Пакет Microsoft Word / Office: VBA, макросы (встроенные / настраиваемые), поля, строительные блоки.
• Mac: командные файлы, командная строка.
• Madcap Flare: макросы, сценарии сборки, переменные. Flare построен на простых текстовых файлах, что открывает огромные возможности.

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

• Вы можете переименовать файл?
• Вы указываете имя файла в месте назначения?
• Что, если файл с таким именем там уже существует? Он перезаписан? Как вы проинформированы?

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

Третий аспект - продемонстрировать то, что вы узнали. Важная задача при написании документации по API - показать пользователям, что делает вызов, предоставить образец кода и, возможно, инструкции для них, как сделать это самим. Короче говоря, сделайте так, чтобы они использовали ваши звонки. Теперь вы можете поделиться своими сценариями с коллегами. Если это будет полезно для вас, это будет полезно для них. В прямом смысле сценарий для группового процесса можно использовать без изменений. Косвенным образом это вдохновляет их на новые идеи. Моя любимая часть проекта автоматизации - это когда пользователи начинают спрашивать: «Сможете ли вы это сделать…?» Сейчас они придумывают идеи. В этом весь смысл документации по API.

# 4 Изучите командную строку

DOS не мертв, и Linux нельзя убить. Командная строка, это черное окно, в котором вы должны все вводить, все еще существует. Я знаю. Это же 21 век, верно? В Windows он возвращается. Для Unix и Linux это никуда не делось. Тем не менее, в мире документации API это приспособление, и вам нужно его использовать. В качестве примеров:

• Git, популярная система управления кодом, использует командную строку. Да, есть графические приложения, которые позволяют обойти это, но в конечном итоге вам лучше просто использовать версию для командной строки.
• Установщик приложений. Некоторые приложения предназначены только для работы с командной строкой. NPM, Sudo или OpenAPI CLI. Возможно, вы не слышали о них, но они широко используются в сообществе API.

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

Ранее упоминалось о сценариях, и это командная строка. В Windows пакетный файл объединяет отдельные строки скриптов в одну команду.

# 5 Не беспокойтесь об инструментах

В сообществе технического писателя писатели тесно связаны со своими инструментами. Многие инструменты перечисляют требования к работе, такие как Word, DITA, Flare, Adobe Suite, как если бы они классифицируют людей по инструментам, которые они знают. Да, инструменты важны. Однако фундаментальным отличием является то, что сообщество документации API рассматривает инструменты только как средство для достижения цели. На это есть две причины.

Во-первых, инструментов так мало, что приходится использовать все, что есть под рукой.

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

• Файлы OpenAPI (ранее известные как Swagger). Это стандарт в сообществе документации API, это просто текстовые файлы. Любой текстовый редактор может их изменять. Обычно авторы используют те редакторы, которые используют их разработчики, например, Intellij, Visual Studio или редактор Swagger. В идеале вы должны иметь возможность знать достаточно, чтобы использовать Блокнот для выполнения работы. После этого инструменты просто превращаются в приспособление для выполнения работы.
• Текстовые редакторы, такие как NotePad ++ и, наконец, NotePad. Могут быть другие файлы, скрипты, файлы журналов, файлы базы данных, которые вам нужно открыть, посмотреть на что-то или, возможно, что-то изменить.
• REST звонки. Скорее всего, они составляют основу вашей работы и потребуют вызовов REST, поэтому вы будете использовать Postman или cURL, редактор командной строки.
• Компиляция. Вы можете использовать IDE, например Intellij или Visual Studio, или командную строку, возможно, для компиляции проектов OpenAPI.
• Базы данных. Большинство функций REST обращаются к базе данных. Возможно, вам потребуется подтвердить некоторые значения или даже изменить данные, чтобы вы могли проверить звонок. Такой редактор, как Microsoft SQL Studio.
• Редактор изображений.
• FTP для передачи веб-файлов.
• Уценка, HTML, CSS.
• Word, для форматирования таблиц.
• Регулярные выражения (regex или grep). Это поиск по шаблону, а не поиск буквального символа. Совместите это с многофайловым редактором, таким как NotePad ++, и вы сможете искать в тысячах файлов одновременно определенный шаблон.

Серьезно, вы можете использовать почти все это за один день. Как упоминалось ранее, важно знать, что такое теория, а после этого реализация - это просто детали, которые вы можете найти.

# 6 Никогда не говори «Я знаю это».

Самое разрушительное, что можно сказать кому-либо, - это «Я знаю это». Это закрывает разговор. Когда вы разговариваете с разработчиком или предметным экспертом, позвольте им поговорить. Даже если вы действительно уже знаете, что они говорят, позвольте им сказать это. На это есть три причины.

Вы, наверное, еще этого не знаете.

Они могут вести себя с другой точки зрения или под другим углом. Они могут иметь дополнительное использование, дополнительную информацию или вести историю в другое место.

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

# 7 Примеры, примеры, примеры

Примеры - это не другое дело, они единственное. Примеры важны в мире технического письма, но они имеют особое значение в мире программирования. Их используют тремя способами:

Индивидуальные звонки.

В примере вызова показано форматирование и использование параметров. Разработчики любят копировать и вставлять.

Формат звонка.

Важность примеров вызовов заключается в том, что они показывают форматирование и порядок параметров. Поскольку все вызовы являются текстами, недостаточно просто иметь синтаксис или даже описание. В качестве примера ниже приводится команда копирования DOS, которая по-прежнему актуальна из-за сценариев командных файлов Windows. Синтаксис:

КОПИРОВАТЬ [/ D] [/ V] [/ N] [/ Y | / -Y] [/ Z] [/ L] [/ A | / B] источник [/ A | / B] [+ исходник [/ A | / B]

[+…]] [Пункт назначения [/ A | / B]]

Это трудно читать, и еще труднее быстро сделать полезный звонок. Примеры позволяют быстро с этим справиться. И они могут просто скопировать и вставить нужную команду, что поможет сделать вас еще более популярными среди разработчиков.

Скопируйте файл в указанное место:
Скопируйте April_Report.doc c: \ monthreports

Скопируйте файл в указанное место и измените имя файла:
Скопируйте April_Report.doc c: \ monthreports \ 2021_April_Report.doc

Скопируйте файл из нетекущего местоположения в отдельное и измените имя:
Скопируйте c: \ currentmonth \ April_Report.doc c: \ monthreports \ 2021_April_Report.doc

Скопируйте группу файлов с подстановочными знаками в указанное место:
Скопируйте currentMonths *. * C: \ monthreports

Скопируйте три указанных файла в указанное место:
Скопируйте April_Report.doc + March_Report.doc + Feburary_Report.doc c: \ monthreports

Копирование файлов, проверка копии и автоматическая перезапись существующих файлов:
Copy / V / Y April_Report.doc c: \ monthreports

Скопируйте три указанных файла в указанное место, проверьте копию и автоматически перезапишите существующие файлы, а также укажите, что новый файл будет двоичным файлом:
Copy / V / Y April_Report.doc / B + March_Report.doc + Feburary_Report.doc / B c: \ monthreports

Фрагменты кода.

Фрагменты кода - это многострочные примеры. Часто вызов требует настройки, определения переменной или обработки в определенном порядке. Отрывки показывают эту последовательность.

Полные приложения.

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

Это позволяет увидеть общую картину. Отдельный вызов может возвращать массив записей, но просмотр этих записей, например, сбор списка имен - это то, чего многие авторы не делали. Это позволит вам еще больше посочувствовать разработчикам.

Как и со всеми примерами кода, это требует меньше усилий для разработчиков. Они могут скопировать проект и, как всегда, просто изменить нужные разделы или значения.

использованная литература

Ниже приводится неполный список ресурсов документации API.

WriteOnce.org
Роберт Делвуд
https://WriteOnce.org

Я бы лучше написал
Том Джонсон
https://idratherbewriting.com/

"Привет мир!" - Руководство программиста по написанию документации API
https://docs.microsoft.com/en-us/archive/msdn-magazine/2010/november/msdn-magazine-hello-world-a-coder%E2 % 80% 99s-guide-to-writing-api-documentation

Программируемый Интернет
https://www.programmableweb.com/

Просто: API, связанные с НАСА
http://api.open-notify.org/iss-now.json

Не так просто, но одинаково интересно: продукты и API Google
https://about.google/intl/en/products/?tab=qh

10 наиболее эффективных команд оболочки и приемов командной строки
https://betterprogramming.pub/the-most-productive-shell-commands-and-command-line-tricks-ec1415283259