Перевод статьи «Documenting a New Feature».
В этой статье вы найдете не шаблон, а скорее чек-лист, но я думаю, что он все равно многим будет полезен. Все, о чем пойдет речь ниже, следует учитывать при составлении документации для новой функции.
Необходимые предварительные условия
Мне нравится эта цитата. Хотелось бы узнать, откуда ее взял Дэн.
Если вы преподаете, это должно быть вашим девизом. А если вы занимаетесь разработкой, то этим подходом стоит воспользоваться при составлении документации.
Но в том, что касается документации, все же стоит сделать одну оговорку. Предполагать нулевые знания не всегда практично. Вместо этого лучше обозначить свои допущения относительно знаний пользователя. Задайте себе несколько вопросов и постарайтесь ответить на них как можно более объективно!
Примечание. Создавая что-то, легко сродниться со своим творением и забыть о том, как мало о нем знают другие люди.
Наличие каких знаний у пользователя можно допустить, составляя документацию?
Поскольку речь идет о новом функционале, он, скорее всего, существует в рамках большой экосистемы. В своем объяснении работы новой функции вы будете использовать термины и концепции, знакомые (вероятно) опытным пользователям вашей системы, однако новички могут о них не знать. Объясните эти термины сразу или укажите, где можно почитать о них.
Хорошим примером может послужить документация новой конечной точки API. При ее составлении разумно будет предположить, что пользователь уже знаком с самим API. Добавьте для читателя нужные ссылки или очень краткое пояснение основ. Возможно, ему потребуется что-то дополнительно почитать, прежде чем браться за новую информацию.
Что у пользователя должно быть установлено, чтобы этот новый функционал можно было настроить и запустить?
Этот вопрос немного напоминает предыдущий, но он более «материален». Что и как пользователь должен установить на своем компьютере, чтобы ваш функционал мог работать?
Здесь можно много всего назвать (как и упустить), но вот небольшой список того, о чем следует подумать:
- Предполагается ли, что у пользователя уже есть рабочий проект?
- Нужно ли пользователю создавать где-нибудь отдельный аккаунт?
- Потребуется ли для использования функционала какой-то ключ?
- Нужно ли будет что-то скачивать?
- Нужно ли будет что-то настраивать?
- Должен ли пользователь иметь данные какого-то конкретного вида или хранить их в каком-то определенном месте?
- Есть ли какие-то зависимости, которые должны быть установлены?
Если вы включили в документацию свои допущения относительно знаний пользователя и дали ссылки на нужные разделы первичной документации, некоторые подробности, указанные в тех разделах, сейчас можно уже опустить.
Хорошим примером может послужить скачивание Node.js. Если вы исходите из того, что пользователь уже подготовил все для работы с API, а описание подготовки включает обязательное наличие Node.js, в документации своей функции вы можете уже об этом не писать. Главное, не забудьте в самом начале оговорить свои допущения.
Для чего предназначен этот функционал, что он делает?
Объяснение того, что делает новая функция, это одна из самых важных вещей в документации. Просматривая документацию, пользователь должен иметь возможность понять, что он получит, если выполнит все инструкции. Суть в том, чтобы человек мог сразу решить, хочет ли он все это проделывать ради получения конечного результата.
Здесь обычно достаточно краткого пояснения. Можно приложить ссылку на пример или скриншот.
Как настроить этот функционал?
Этот раздел — сама суть документации. В этом разделе вы уже не можете предполагать наличие какие-либо знаний у пользователя, потому что речь идет о совершенно новой для него функции. Это вы работали над ней месяцами, а пользователь видит ее впервые.
Этот раздел лучше всего изложить в виде пошагового руководства. Что-то в таком духе:
- Установите Х.
- Настройте Y.
- Создайте файл Z по адресу P.
Доступны ли в вашем функционале какие-то дополнительные опции или флаги?
В качестве основного примера вы, скорее всего, приведете наиболее благоприятный сценарий. Старайтесь сделать так, чтобы он покрывал как можно большее количество вариантов использования. Но при этом не следует забывать о других опциях.
Есть ли в вашем функционале другие настройки? Флаги? Альтернативные конфигурации? Другие параметры API?
Если да, — укажите это в документации! Один из моих любимых вариантов — включить в этот раздел таблицу с опциями, а также типами данных и описаниями. Хороший пример можно найти в README The Gatsby blog theme.
Как пользоваться этим функционалом?
Не забудьте включить этот раздел! Я даже не могу описать, насколько часто в документацию включают инструкции по настройке чего-то нового и при этом забывают привести примеры использования.
Вам использование вашего функционала может казаться очевидным, особенно если что-то аналогичное есть и в других системах. Но я вас уверяю: с точки зрения пользователя все обстоит совсем иначе.
Несколько основных правил:
- Включайте сниппеты кода, где это будет уместно.
- Обязательно указывайте, где можно найти эти отрывки, например, в каком файле.
- Включайте в ваших примерах необходимые импорты.
- Если это возможно, приведите несколько примеров! Людям будет понятнее, если они увидят некий повторяющийся шаблон.
Ссылки на примеры
Будет хорошей идеей показать один пример вверху документации, при объяснении функционала, а затем добавить еще несколько внизу. Некоторые люди предпочитают увидеть функционал в действии, а не читать о нем, так что дополнительные примеры будут кстати.
Фидбэк
Добавьте возможность для обратной связи (если это будет к месту, разумеется). Если вы укажете контакты поддержки или предложите пользователям обратиться к GitHub issues, это позволит вам получить фидбэк от первых пользователей и при необходимости внести какие-то мелкие изменения в ваш функционал (или документацию).
Следующие шаги
Это уже опционально, но лично мне такие вещи в документации очень нравятся. Упомяните о других функциях, связанных с вашей. Поделитесь ссылками на их документацию. Если бы вы только знали, как часто это помогает людям найти то, что они на самом деле искали!
[customscript]techrocks_custom_after_post_html[/customscript]
[customscript]techrocks_custom_script[/customscript]