Реклама

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

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

На предстоящей конференции 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 ноября в Портленде, штат Орегон.

Реклама

Комментарии

Комментарии

Только авторизованные пользователи могут оставлять комментарии.
Пожалуйста, Авторизуйтесь или Зарегистрируйтесь

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

  • Результат 50 баллов
  • Очки рейтинга -4

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

  • Результат 80 баллов
  • Очки рейтинга 4

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

  • Результат 6 баллов
  • Очки рейтинга -10
Последние комментарии

QML - Урок 002. Custom Button in QML Android

Нашел http://doc.qt.io/Qt-5/qtquickcontrols2-customize.html#customizing-button

QML - Урок 002. Custom Button in QML Android

А как кастомайзить Button если использовать QtQuick.Controls 2.0 ? В этом случае пишет Cannot assign to non-existent property "style"

  • EVILEG
  • 15 ноября 2017 г. 13:56

Qt/C++ - Урок 072. Пример векторного редактора на Qt

You need add common QWidget to form, after that you need right-click on this QWidget in the form and select "Promote to..." in Context Menu. After that You will see dialog. In dialog choose Ba...

  • cordsac
  • 15 ноября 2017 г. 3:33

Qt/C++ - Урок 072. Пример векторного редактора на Qt

Sir,In this form design how did you add verectanglesettings.ui,vepolylinesettings.ui UI's to this mainwindow.ui ? have any QT tool to add so. this image shows what I meaning.

Сейчас обсуждают на форуме
  • Docent
  • 21 ноября 2017 г. 19:39

Видео на сцене QGraphicsScene, как правильно сделать?

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

Многопоточность. Ошибки при обращении к переменной

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

как отключить событие при открытии формы?

как обойти проблему: см. комментарий кода - может кто подскажет. TableView { id: table model: tableModel anchors.fill: parent focus: true Component.onComple...

  • EVILEG
  • 21 ноября 2017 г. 14:40

QGraphicsItem конструктор с параметрами

За что именно отвечают x_c , y_c ? Это положение объекта на графической сцене? Тогда лучше не в методе paint их применять, а через метод setPo...

  • EVILEG
  • 21 ноября 2017 г. 1:36

QGraphicsItem

Я так понимаю, вы каким-то образом передаёте указатель на отрисовываемый текст, то есть на QString. Но лучше добавить переменную в объявление класса, которая будет отвечать за текст, и п...