Что делает документацию хорошей
Документация помещает полезную информацию в головы других людей. Следуйте этим советам, чтобы писать лучшую документацию.
Делайте документацию удобной для быстрого просмотра
Мало кто читает линейно сверху вниз. Они будут перескакивать, пытаясь понять, какая часть решает их проблему, если такая есть. Чтобы сократить время поиска и увеличить шансы на успех, сделайте документацию удобной для быстрого просмотра.
Разделяйте содержимое на секции с заголовками. Заголовки секций служат ориентирами, показывая читателям, стоит ли углубляться или лучше перейти дальше.
Предпочитайте заголовки с информативными предложениями, а не абстрактными существительными. Например, если вы используете заголовок «Результаты», читателю придется заглядывать в текст, чтобы понять, о каких результатах идет речь. В отличие от этого, заголовок «Передача потока сократила время до первого токена на 50%» сразу дает читателю нужную информацию без лишних переходов.
Включайте оглавление. Оглавления помогают читателям быстрее находить информацию, как хэш-таблицы обеспечивают более быстрый доступ по сравнению со связанными списками. Оглавления также имеют второе, часто недооцениваемое преимущество: они дают читателям подсказки о содержании документа, что помогает понять, стоит ли его читать.
Держите абзацы короткими. Короткие абзацы легче просматривать. Если у вас есть важный пункт, рассмотрите возможность выделить его в отдельный абзац из одного предложения, чтобы снизить вероятность того, что его пропустят. Длинные абзацы могут «зарыть» информацию.
Начинайте абзацы и секции с коротких тематических предложений, которые дают самостоятельный обзор. При быстром просмотре люди обращают непропорционально много внимания на первое слово, первую строку и первое предложение раздела. Пишите эти предложения так, чтобы они не зависели от предыдущего текста. Например, предложение «Основываясь на этом, теперь поговорим о более быстром способе» будет бессмысленным для тех, кто не читал предыдущий абзац. Лучше напишите так, чтобы предложение понималось само по себе: например, «Векторные базы данных могут ускорить поиск по embedding’ам.»
Ставьте ключевые слова в начало тематических предложений. Читателям легче быстро просматривать текст, если им достаточно прочитать одно-два слова, чтобы понять, о чем абзац. Поэтому при написании тематических предложений предпочитайте ставить тему в начало предложения, а не в конец. Например, если вы пишете абзац о векторных базах данных в середине длинной статьи о поиске по embedding’ам, вместо «Поиск по embedding’ам может быть ускорен векторными базами данных» лучше написать «Векторные базы данных ускоряют поиск по embedding’ам.» Второй вариант лучше для быстрого просмотра, потому что сразу ставит тему абзаца впереди.
Выносите основные выводы вперед. Размещайте самую важную информацию в начале документов и секций. Не стройте большое логическое построение по методу Сократа. Не вводите процедуру до того, как представите результаты.
Используйте маркированные списки и таблицы. Списки и таблицы облегчают просмотр документации. Используйте их часто.
Жирным выделяйте важный текст. Не бойтесь выделять жирным шрифтом важные моменты, чтобы читателям было проще их найти.
Пишите грамотно
Плохо написанный текст сложно читать. Минимизируйте нагрузку на читателей, хорошо написав текст.
Делайте предложения простыми. Разделяйте длинные предложения на два. Убирайте наречия. Удаляйте лишние слова и фразы. Используйте повелительное наклонение, если применимо. Следуйте советам из учебников по письму.
Пишите предложения, которые можно однозначно разобрать. Например, рассмотрим предложение «Title sections with sentences.» Когда читатель видит слово «Title», его мозг еще не понимает, это существительное, глагол или прилагательное. При этом ему приходится задействовать мозг, чтобы сопоставить значение по тексту, что может вызвать заминку, если он неправильно предположит смысл. Предпочитайте предложения, которые проще парсятся (например, «Write section titles as sentences»), даже если они длиннее. Аналогично избегайте словосочетаний, которые сложно разобрать, например «Bicycle clearance exercise notice».
Избегайте лево-ветвящихся предложений. Лингвистические деревья показывают, как слова связаны друг с другом в предложениях. Лево-ветвящиеся деревья требуют от читателей держать в памяти больше информации, чем право-ветвящиеся предложения, подобно ширинному и глубинному обходу. Пример лево-ветвящегося предложения: «You need flour, eggs, milk, butter and a dash of salt to make pancakes.» Здесь вы не понимаете, что именно нужно, пока не дойдете до конца предложения. Более легко читаемая право-ветвящая версия: «To make pancakes, you need flour, eggs, milk, butter, and a dash of salt.» Следите за предложениями, где читателю нужно долго удерживать слово в памяти, и попробуйте переформулировать их.
Избегайте указательных местоимений (например, «this»), особенно в переходе между предложениями. Вместо «Building on our discussion of the previous topic, now let’s discuss function calling» лучше сказать «Building on message formatting, now let’s discuss function calling.» Второе предложение легче понять, потому что не заставляет читателя вспоминать предыдущую тему. Ищите возможности полностью убрать указательные местоимения, например «Now let’s discuss function calling.»
Будьте последовательны. Мозг человека отлично распознает шаблоны. Несовпадения раздражают или отвлекают читателей. Если мы везде используем Title Case, придерживайтесь этого. Если везде ставим заключительные запятые, сохраняйте их. Если все ноутбуки из Cookbook названы со знаками подчеркивания и в предложном регистре, используйте это везде. Не делайте ничего, что заставит читателя подумать «хм, странно.» Помогайте им сосредоточиться на содержании, а не на несоответствиях.
Не указывайте читателям, что они должны думать или делать. Избегайте фраз вроде «Now you probably want to understand how to call a function» или «Next, you’ll need to learn to call a function.» Обе предположения о состоянии читателя могут раздражать или уменьшать доверие. Используйте формулировки, которые не делают предположений о состоянии читателя, например: «To call a function, …»
Будьте максимально полезны
Люди приходят к документации с разным уровнем знаний, знанием языка и терпения. Даже если мы ориентируемся на опытных разработчиков, следует стараться писать документацию, полезную для всех.
Пишите просто. Объясняйте проще, чем думаете, что нужно. Многие читатели могут не быть носителями английского. Многие могут сильно запутаться в технической терминологии и мало иметь ресурсов для восприятия английских предложений. Пишите просто. (Но не упрощайте чрезмерно.)
Избегайте аббревиатур. Пишите слова полностью. Стоимость для экспертов низка, а польза для новичков велика. Вместо IF напишите «instruction following». Вместо RAG — «retrieval-augmented generation» (или мой предпочтительный термин: процедура «ищи-запрашивай»).
Предлагайте решения потенциальных проблем. Даже если 95% наших читателей знают, как установить пакет Python или сохранить переменные окружения, все равно стоит заранее это объяснить. Для экспертов объяснения несложно пропустить. Но новичкам без этих объяснений будет сложно, они могут застрять или даже уйти. Помните, даже опытный инженер JavaScript или C++ может быть новичком в Python. Лучше объяснять больше, чем меньше.
Предпочитайте терминологию, которая конкретна и точна. Жаргон — зло. Оптимизируйте документацию для новичков, а не для себя. Например, вместо «prompt» лучше «input». Вместо «context limit» — «максимальный лимит токенов». Эти выражения более очевидны и вероятно лучше жаргона, развитого в эпоху базовых моделей.
Держите примеры кода общими и переносимыми. В демонстрациях кода старайтесь минимизировать зависимости. Не заставляйте пользователей устанавливать дополнительные библиотеки. Не заставляйте их прыгать между страницами и разделами. Старайтесь сделать примеры простыми и автономными.
Приоритизируйте темы по значимости. Документация, покрывающая частые проблемы (например, как считать токены), несоразмерно более ценна, чем документация по редким вопросам (например, оптимизация эмодзи-базы данных). Приоритизируйте соответственно.
Не учите плохим привычкам. Если ключи API не должны храниться в коде, никогда не приводите пример, где ключ хранится в коде.
Вводите темы с широкого обзора. Например, объясняя, как программировать хороший рекомендатель, начните с краткого упоминания, что рекомендации встречаются повсеместно в интернете — от видео на YouTube до товаров Amazon и статей Wikipedia. Широкий ввод в узкую тему помогает людям чувствовать себя увереннее перед погружением в новую область. И если текст хорошо написан, те, кто уже знаком с темой, тоже получат удовольствие.
Нарушайте эти правила, если есть веские причины
В конечном итоге делайте так, как считаете правильным. Документация — это упражнение в эмпатии. Поставьте себя на место читателя и сделайте то, что поможет им больше всего.