Для кода, программного обеспечения с открытым исходным кодом, инструментов и т. Д.

Вы когда-нибудь слышали фразу «Прочтите Прекрасно написанное руководство?» Руководство, являющееся основным источником истины и ценностью для того инструмента или структуры, которые вы изучаете; по крайней мере, так должно быть. Как и у многих из вас, разработчиков, у членов TechMasters есть некоторые болевые точки и мудрые слова, которыми они могут поделиться в отношении того, как следует писать или читать документацию (или «документы»), которые я резюмировал здесь. Как и программное обеспечение, документация должна быть тщательно спланирована, организована и оптимизирована для удобства использования.

Элемент №1: Приглашайте

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

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

Введение

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

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

# 2: По возможности будьте лаконичны

Чтобы перестраховаться, предположите наихудшую из возможных ситуаций для ваших читателей: они нетерпеливы, находятся под давлением времени, неопытны или слишком опытны, чтобы беспокоиться о подробных объяснениях и трепе. У ваших документов может быть несколько путей, но должен быть хотя бы один очевидный и безболезненный путь.

Будь то README или Быстрый старт, постарайтесь достичь того, что ищут ваши читатели: руководства, которое поможет им перейти от ничего к чему-то с помощью элементарного понимание менее чем за час (хотя менее 10 минут будет особенно полезным - стремитесь к еще меньшему). Кроме того, не называйте своего гида чем-то вроде «Быстрый старт за 10 минут», потому что это может быть обещание, которое вы не сможете выполнить. Меньше всего ваши документы должны быть длинными и разочаровывающими.

Наконец, постарайтесь не опекать своих читателей такими словами, как «просто», «просто добавь…» или «легко». Опытные разработчики закатывали глаза, а разочарованные пользователи раздражались. Документация по своей сути должна быть «простой» и «легкой», поэтому нет необходимости объявлять ее в каждом втором предложении.

# 3: Добавьте необязательные полезные примеры

Необязательно, то есть вам не нужно помещать пример рядом с каждым предложением, если это не необходимо. Полезно, так как не используйте foo() или var bar = baz; они бессмысленны и не помогают пользователям называть свои переменные!

Для интерфейсных инструментов один надежный пример должен быть размещен сразу после вашего представления - например, привлекательный, низко висящий плод. Если пример можно визуализировать, обязательно вставьте самозаполняющееся приложение, такое как codepen или jsfiddle.

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

Меня меньше интересует интерактивность; Меня гораздо больше волнует наличие множества примеров выходных данных с учетом конкретных параметров запроса. Я также сталкивался с системой, в которой «интерактивная» версия документации не работала на последней версии API и поэтому часто была устаревшей. - Брайан Айриш

# 4: Напишите самодокументированный код

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

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

Я бы сказал, что если вы не собираетесь документировать в удобочитаемом формате (markdown, html и т. Д.), По крайней мере, прокомментируйте свои открытые методы в своей кодовой базе, чтобы, когда другие читают, он был удобоваримым. - Нидзико

# 5: Поддерживайте свои документы

Ваши документы являются частью вашего программного обеспечения. Таким образом, их необходимо поддерживать и обновлять (а иногда и версионировать) с каждым выпуском. Они являются частью вашей разработки; поэтому, если вы планируете включать документы, уделите им время и усилия.

Создавайте свое сообщество

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

  1. Дополните свою документацию, чтобы прояснить пропущенные моменты.
  2. Ответьте на общие вопросы в FAQ.
  3. Создавайте подробные примеры, охватывающие общие сценарии.
  4. Записывайте видеоуроки в длинных и коротких форматах, чтобы дополнять интерактивные примеры. Наличие отдельного репозитория с загружаемыми примерами помогает пользователям привлекать внимание, следя за вашим видео.
  5. Блог об общих пользовательских историях, применимых к вашему проекту.

Шаблоны

В Интернете есть десятки шаблонов документов, но они настолько же полезны, насколько и их содержание. Вот несколько советов, с которых можно начать:

Отличные примеры документации

Простые вещи должны быть простыми, сложные - возможными. - Алан Кей



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



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



О Visual Studio Code можно сказать много хорошего, но их вводная документация и журналы изменений восхитительны. Все подробные обновления пользовательского интерфейса имеют краткое описание и сопровождаются анимированными GIF-файлами. На большинстве страниц есть удобные ссылки, которые могут помочь пользователям обнаружить полезные функции, которые они, возможно, не искали в ином случае. В общем, документация может помочь пользователям освоить функции VSCode за очень короткое время.



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

"По-разному"

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

Если у вас есть документация, которую вы хотите, чтобы я изучил, оставьте комментарий или присоединитесь к беседе на TechMasters.chat! Мы будем рады поделиться своим опытом.