© EVILEG 2015-2018
Рекомендует хостинг
TIMEWEB

Секреты написания хорошей документации

Документация

На предстоящей конференции APIStrat в Портленде Тейлор Барнетт изучит различные принципы проектирования документации и обсудит лучшие практики.

Тейлор Барнетт, инженер сообщества в Keen IO, говорит, что практика и постоянные итерации являются ключевыми вещами для написания хорошей документации. На предстоящей конференции по стратегии и практике API 2017, которая будет проходить с 31 октября по 2 ноября в Портленде, Барнетт объяснит различные типы документаций и опишет некоторые лучшие практики.

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

Linux Foundation: Что привело вас к этому разговору? Встречались ли вам проекты с плохой документацией?

Тейлор Барнетт: В прошлом году мой товарищ по команде, Мэгги Ян, и я возглавляли работу над улучшением контента и документации для разработчиков в Keen IO. Не секрет, что разработчики любят отличную документацию, но многие компании, разрабатывающие API, не всегда оснащены ресурсами, чтобы иметь таковую. В результате все мы сталкиваемся с большим количеством плохой документации, когда пытаемся использовать инструменты разработчика и API.

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

Барнетт: В крупных компаниях это определенно может быть правдой, хотя во многих компаниях документация по-прежнему принадлежит различным командам. Тем не менее, потребность в улучшении взаимодействия по-прежнему имеется. Один из способов улучшить сотрудничество - писать документацию в процессе разработки продукта на раннем этапе. Если вы подождете, пока все будет сделано и продукт будет готов к выпуску, люди, пишущие документацию, будут чувствовать себя оторванными от процесса и считать себя второстепенными. Если люди, работающие над разработкой продукта, сотрудничают на раннем этапе, улучшается не только продукт, но и документация. Люди, которые пишут документацию, обычно проводят некоторое время, чтобы понять API или инструмент, о котором они пишут, поэтому они становятся только лучше, когда могут работать с людьми, которые этот продукт разрабатывают. Кроме того, они могут дать бо'льшую обратную связь с точки зрения пользователя намного раньше.

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

Linux Foundation: Как следует разработчикам подходить к документации?

Барнетт: Большинство разработчиков хорошо знакомы с идеей Test Driven Development (TDD), но насколько знакомы они с разработкой Documentation Driven Development (DDD)? Шаги DDD:

  1. Напишите или обновите документацию,
  2. Получите отзывы об этой документации,
  3. Напишите тест на отказ в соответствии с этой документацией (TDD),
  4. Напишите код для прохождения теста на отказ,
  5. Повторите.

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

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

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

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

Барнетт: Раньше я думал, что разработчики - это лучшие люди для того, чтобы писать документацию для других разработчиков, потому что они сами ими являются. Я по-прежнему считаю, что это отчасти верно, т.к. некоторые разработчики обладают большим количеством знаний. Если прошло какое-то время, после того как разработчик что-то изучил, может существовать так называемое «проклятие знания». Чем больше вы знаете, тем больше вы забываете, как это было раньше. Вот почему я люблю говорить об эмпатической документации.
Вам нужно сопереживать пользователю на другом конце. Не думайте, что он знает, как сделать что-либо, дайте пользователю ресурсы, чтобы заполнить шаги, которые могут показаться вам «легкими». Кроме того, мнение, что что-то «легко» или «просто», когда это не работает у пользователя, - это самое страшное чувство для него. Это заставляет ваших пользователей сомневаться в себе, чувствовать разочарование и кучу других негативных эмоций. Всегда старайтесь помнить, что вам нужно быть чутким!

Linux Foundation : Насколько важны инструменты для создания документации?

Барнетт: Очень важны! Раньше я упоминал об использовании GitHub для обзоров. Я также рекомендовал бы провести постоянное интеграционное тестирование на вашем сайте документации, если вы не используете такую ​​услугу, как ReadMe или Apiary, чтобы убедиться, что вы ее не сломаете. Связанная с этим тема: создаете ли вы свой собственный продукт или используете сервис? Инструменты могут быть полезны, но они могут быть не всегда оптимальными. Вы должны найти баланс на основе ваших текущих ресурсов. Наконец, я бы рекомендовал попробовать книгу Энн Джентль, "Docs Like Code". Она много раз поднимает тему инструментов в книге.

Linux Foundation: Кому следует присутствовать на вашей сессии?

Барнетт: Всем! Просто шучу. Если вы являетесь кем-то в роли разработчика, таким как разработчики взаимоотношений , евангелисты, адвокаты, маркетологи и т. Д., Если вы находитесь в команде продакшена разработчиком продукта или платформы, или если вы разработчик или инженер, который хочет писать отличные документации.

Linux Foundation: Каков основной посыл вашего беседы?

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

Узнайте больше в беседе Тейлор Барнетт на конференции APIStrat, которая состоится с 31 октября - 2 ноября в Портленде, штат Орегон.

Комментарии

Комментарии

Только авторизованные пользователи могут оставлять комментарии.
Пожалуйста, Авторизуйтесь или Зарегистрируйтесь
15 июня 2018 г. 12:42
Nicky

C++ - Тест 004. Указатели, Массивы и Циклы

  • Результат 100 баллов
  • Очки рейтинга 10
15 июня 2018 г. 12:36
Nicky

C++ - Тест 003. Условия и циклы

  • Результат 57 баллов
  • Очки рейтинга -2
15 июня 2018 г. 12:29
Nicky

C++ - Тест 001. Первая программа и типы данных

  • Результат 46 баллов
  • Очки рейтинга -6
Последние комментарии
18 июня 2018 г. 7:12
EVILEG

PyQt5 - Урок 007. Работаем с QML QtQuick (Сигналы и слоты)

Я вот сейчас банальность скажу, но у меня всё работало. Так что даже и не знаю, надо на код смотреть, что ещё у вас добавлено или отсутствует из библиотек. P/S/ Извините, вы сейчас вс...
18 июня 2018 г. 7:10
EVILEG

Qt/C++ - Урок 042. PopUp уведомление в стиле Gnome с помощью Qt

Недоработки, вряд ли этот зверь вообще является официально поддерживаемым
18 июня 2018 г. 7:01
EVILEG

QML - Урок 016. База данных SQLite и работа с ней в QML Qt

что-то мне сдаётся, что здесь просто пересобрать проект нужно с удалением build каталога
18 июня 2018 г. 7:00
EVILEG

Qt - WinAPI. Как показать запущенное приложение поверх своего приложения

Если зарыться в API системы, то, думаю, что можно, тут тоже использовался WinAPI.
16 июня 2018 г. 15:19
pro100belik

Qt - WinAPI. Как показать запущенное приложение поверх своего приложения

А можно по ID процесса  выводить на передний план окно? myProcess->processId();
Сейчас обсуждают на форуме
19 июня 2018 г. 7:56
EVILEG

как редактировать порядок обхода этементов по нажатию TAB в Qt5 qml

Что-то наподобие такого TextField { Keys.onReturnPressed: nextItemInFocusChain().forceActiveFocus()}
19 июня 2018 г. 6:31
kabanov

Как сохранить фокус в TextField после перезагрузки модели

Rectangle { ListView { id: listView delegate: Item { id: cDelegate Item { Row { ComboBox { ...
18 июня 2018 г. 10:51
alex_lip

Qml and JavaScript

В том то и дело что просто в JS так нельзя Если использовать state - onReleased - не нужен вот так все работает Text { ...
18 июня 2018 г. 7:16
EVILEG

почему не выполняется код после вызова слота?

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

Рекомендуемые страницы