На предстоящей конференции 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:
- Напишите или обновите документацию,
- Получите отзывы об этой документации,
- Напишите тест на отказ в соответствии с этой документацией (TDD),
- Напишите код для прохождения теста на отказ,
- Повторите.
Это может быть отличным способом для разработчиков сэкономить большое количество времени и не тратить его слишком много на плохо разработанные функции. Как говорит Исаак Шлютер, соучредитель npm, о разработке документации - «Это эффективный способ повысить производительность за счет сокращения как частоты, так и стоимости ошибок». Наш мозг может хранить ограниченное количество информации одновременно. В компьютерных терминах - размер нашей рабочей памяти довольно мал. Записывание той информации, о которой мы думаем, это способ «выгрузить значительный кусок мыслей без потерь данных», позволяя нам думать медленнее и осторожнее.
Например: В Keen IO мы недавно разделили нашу библиотеку JavaScript на три разных модуля. Это решение было вдохновлено документацией, которую мы поддерживали. Мы попытались упорядочить документацию, но ее было слишком много, чтобы охватить всю с ограниченным вниманием. В шуме были скрыты многие важные детали и функции. Например, если бы вся документация была написана раньше, возможно, мы приняли это решение раньше.
Кроме того, разработчику, который сам пишет документацию, важны постоянное повторение и практика. Ваша первая версия документации не будет отличной, но, сосредоточившись на попытке написать понятный текст, со временем она станет лучше. Кроме того, важно наличие другого человека, не знакомого с продуктом, который может сделать обзор на вашу документацию.
Linux Foundation: если разработчики пишут документацию для других разработчиков, как они могут думать как пользователи?
Барнетт:
Раньше я думал, что разработчики - это лучшие люди для того, чтобы писать документацию для других разработчиков, потому что они сами ими являются. Я по-прежнему считаю, что это отчасти верно, т.к. некоторые разработчики обладают большим количеством знаний. Если прошло какое-то время, после того как разработчик что-то изучил, может существовать так называемое «проклятие знания». Чем больше вы знаете, тем больше вы забываете, как это было раньше. Вот почему я люблю говорить об эмпатической документации.
Вам нужно сопереживать пользователю на другом конце. Не думайте, что он знает, как сделать что-либо, дайте пользователю ресурсы, чтобы заполнить шаги, которые могут показаться вам «легкими». Кроме того, мнение, что что-то «легко» или «просто», когда это не работает у пользователя, - это самое страшное чувство для него. Это заставляет ваших пользователей сомневаться в себе, чувствовать разочарование и кучу других негативных эмоций. Всегда старайтесь помнить, что вам нужно быть чутким!
Linux Foundation : Насколько важны инструменты для создания документации?
Барнетт: Очень важны! Раньше я упоминал об использовании GitHub для обзоров. Я также рекомендовал бы провести постоянное интеграционное тестирование на вашем сайте документации, если вы не используете такую услугу, как ReadMe или Apiary, чтобы убедиться, что вы ее не сломаете. Связанная с этим тема: создаете ли вы свой собственный продукт или используете сервис? Инструменты могут быть полезны, но они могут быть не всегда оптимальными. Вы должны найти баланс на основе ваших текущих ресурсов. Наконец, я бы рекомендовал попробовать книгу Энн Джентль, "Docs Like Code". Она много раз поднимает тему инструментов в книге.
Linux Foundation: Кому следует присутствовать на вашей сессии?
Барнетт: Всем! Просто шучу. Если вы являетесь кем-то в роли разработчика, таким как разработчики взаимоотношений , евангелисты, адвокаты, маркетологи и т. Д., Если вы находитесь в команде продакшена разработчиком продукта или платформы, или если вы разработчик или инженер, который хочет писать отличные документации.
Linux Foundation: Каков основной посыл вашего беседы?
Барнетт: Любой может писать документации, но с некоторой практикой, итерацией и работой над различными навыками написания документации каждый сможет писать отличную документацию.
Узнайте больше в беседе Тейлор Барнетт на конференции APIStrat, которая состоится с 31 октября - 2 ноября в Портленде, штат Орегон.
