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

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

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

Но какую задачу легче выполнить сейчас, в конце первой четверти XXI века, - написать документацию или код? 

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

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

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

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

А как насчет искусственного интеллекта? Многие сообщества выражают обеспокоенность, и технические писатели не стали исключением. Такие задачи, как документирование кода и API, машина действительно выполняет лучше и быстрее. Но если быть честным - это была самая механическая часть работы, и этот факт не вызывает особого сожаления. Больше всего меня беспокоит потеря творческого потенциала, которая наступает после многочасовых попыток найти тот самый запрос к ИИ, после которого он выдаст необходимый текст. Если автоматическое создание unit-тестов или черновых описаний функций - это реальная помощь разработчикам и ускорение процесса поставки нового функционала, то когда речь идет о документации, все не так однозначно. Технические писатели должны быть очень осторожны с ИИ и использовать его без вреда для собственного вдохновения.

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

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

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

Для тех, кто дочитал до конца, хочется оставить небольшой бонус в виде списка статей для дальнейшего чтения на тему создания документации в целом и в сравнении с написанием кода: 

• Перевод статьи из блога - idratherbewriting: Почему так трудно документировать код.

• Блог Atlassian - Как создать идеальную внутреннюю документацию.

• Статья Екатерины Носковой - Аналитика в документации: как увидеть реальную пользу и понять, что улучшать.

А вот пример запроса к ChatGPT, который может помочь улучшить общее качество создаваемого контента (просто замените [параметры] на свои данные):

Ты выступаешь в роли главного редактора компании [отрасль/сфера].
Тебе будет предоставлен текст статьи, разделенный тройными кавычками. Проанализируй текст и предоставь свой ответ в следующем формате:

Заголовок: Название статьи
О чем: Резюмируй текст статьи в 3 пунктах.
Улучшения: Предложи общие улучшения для статьи в 3 пунктах.
Неточности: Подтверди корректность статьи с точки зрения [научная сфера, к которой относится статья, например - сетевое администрирование]. Если будут обнаружены какие-либо неточно описанные понятия, предоставь их список в следующем виде {краткое название/определение понятия} - {краткое резюме того, что было описано неверно} - {краткое правильное описание}.

"""[текст статьи]""""

Не спеши формулировать ответы и проанализируй предложенный текст внимательно.

Для большей конфиденциальности используйте OpenAI API вместо веб-интерфейса или сторонних библиотек.