Осенью 2016 года с моим товарищем по команде было поручено улучшить мою документацию и содержание моей бывшей компании. Мы потратили год на все виды документации — ссылки на API, руководства, учебные пособия и сообщения в блогах. Я писал документацию в течение предыдущих 5 лет, но я не был формально подготовлен в области технического письма. Я был отнюдь не неопытным, хотя, благодаря работе над документацией API для проектов и запуском и обучением мастерских Python Flask в конце моей степени информатики. Это был первый раз, когда я когда-либо мог сосредоточиться на документации, которая позволила мне преследовать мою страсть к оказанию помощи людям всех уровней квалификации в технической документации.
В этом году я многому научились у сообщества Write the Docs, других поставщиков API и моих собственных проб и ошибок. В прошлом году я говорил об этом в беседе «Все, что я хотел, чтобы люди говорили мне о написании документов» на конференции по стратегии и практике API в Портленде, штат Орегон. — обзор того, что я узнал.
Содержание статьи
Как люди действительно читают документацию?
Знаете ли вы это чувство, когда The Onion устрашающе правы? Это как-раз тот случай. Люди могут не физически содрогаться в ваших документах, но есть хорошие шансы, что они делают это мысленно. Я боролся с идеей, что люди не собираются читать то, что я пишу, если я не представим ее самым легко усваиваемым образом. Черт, это может произойти даже в этом блоге. (Примечание для себя: Напомните себе, почему я даже пишу. ?)
В исследовании отслеживания глаз от Neilson Norman Group в 2006 году 232 пользователя просмотрели тысячи веб-страниц. Они обнаружили, что пользователи обычно смотрят на веб-страницы в F-образце:
- «Сначала пользователи читали горизонтальное движение обычно через верхнюю часть области содержимого , Этот начальный элемент образует верхнюю панель F. »
- « Затем пользователи немного перемещаются по странице, а затем просматривают в втором горизонтальном движении, которое обычно покрывает более короткую область, чем предыдущая движение. Этот дополнительный элемент образует нижний бар F. »
- « Наконец, пользователи просматривают левую сторону содержимого в вертикальном движении . Иногда это медленное и систематическое сканирование, которое появляется как сплошная полоска на карте памяти для отслеживания глаз. В других случаях пользователи двигаются быстрее, создавая тепловую карту spottier. Этот последний элемент образует стержень F. »
В исследовании также были обнаружены некоторые альтернативные шаблоны сканирования, такие как шаблон слоя-торта, пятнистый рисунок, шаблон маркировки, обход картины и приверженность шаблон. Я рекомендую просмотреть оставшуюся часть отчета.
Важно отметить, что F-шаблон отрицателен для пользователей, но хороший дизайн контента может помочь предотвратить сканирование F-формы.
Что именно последствия этого в отношении документации?
- В первых двух параграфах должна быть указана самая важная информация
- . Кроме того, первые 3-5 слов критический
- Начать заголовки, абзацы и пункты с ключевыми словами
- Вариации в шрифте (размер текста, ссылки, жирный шрифт и т. Д.) Могут быть необходимы для сохранения
Итак, как вы должны структурировать контент на странице?
- Предотвратить неудачу поиска — убедитесь, что хотят пользователи
- Один идея за абзац, если есть несколько, разделите абзацы
- Пользователи пропустите те вещи, которые выглядят как реклама, поэтому будьте осторожны с тем, как вы показываете изображения
- Не слишком сильно увеличивайте свой контент слишком большой — используйте ширину 65-90 символов
Я узнал некоторые из этих советов из разговора Кевина Берка «Как написать документацию для пользователей, которые не читают». Кевин поддерживал документы Twilio с 2011 по 2014 год.
Кроме того, есть удобство использования абзацев. Подобно The Onion когда вы много раз читаете абзац, вы заглядываете на все это. Итак, почему мы пишем так много абзацев в документах? Давайте проведем эксперимент с документами Keen IO:
Быстро прочитайте это:
В коллекциях событий может быть почти любое имя, но есть несколько правил: имя должно быть не более 64 символов. Он должен содержать только символы Ascii. Это не может быть нулевым значением.
Теперь быстро прочитайте это:
В коллекциях событий может быть почти любое имя, но есть несколько правил:
- Имя должно быть не менее 64 символов.
- Он должен содержать только символы Ascii.
- Он не может быть нулевым значением.
Оба они содержат точный текст . Это не ракетостроение, второе помогает вам лучше понять информацию и за меньшее время. Мы должны помнить, что некоторые абзацы могут выиграть от разрыва в пули.
В более поздней части этой серии я расскажу о разработке и навигации документации.
Образцы кода
]
Что такое документация API без кода, не так ли? Образцы кода находятся во многих наших документах, и наши пользователи на самом деле читают их. Однако проблема заключается в том, что они не всегда читают материал вокруг них, если он не выскакивает на них.
Контекст в образце кода важен для успеха разработчика. Разработчики быстро копируют и вставляют. Вот пример с Keen IO API:
Разработчик быстро копирует и вставляет этот код. И …
Во-первых, как они даже запускают этот файл? Вероятно, узел file_name.js но он не был в коде. Это можно было бы добавить в комментарии наверху.
Хорошо, поэтому они запускают его и … ReferenceError: Keen не определен . ☹️ Клиент Keen никогда не создавался, нет указаний на импорт или требовать сверху, и он работает только в том случае, если они npm установили библиотеку.
Они получают эти исправления и запускают его еще раз … угадайте, что ?! Еще одна ошибка! ☹️ your_project_id и your_write_key никогда не хранились нигде.
Это все, что можно было бы сделать более очевидным в коде.
пример из документов Twilio, который дает хороший контекст конечному пользователю:
Это очень ясно, как вы должны установить библиотеку , включите его в свой код, а затем, что нужно заменить в примере кода, чтобы запустить образец.
Копировать и вставлять ошибки
Поскольку у нас много образцов кода в документах, копирование и вставка становится довольно важным. Вот два примера, где это ломается:
# Скопируйте и вставьте следующую команду
$ gem install rails
Кажется довольно безвредным, не так ли? Подумайте еще раз, что происходит, когда вы отправляете копию и вставляете ее в свою командную строку? Вы, скорее всего, получите:
bash: команда не найдена: $
Это распространенная ошибка. Либо вы хотите, чтобы ваша команда отображалась так, как в командной строке, или вы случайно скопировали ее над собой. Я бы рекомендовал просто оставить $ . Вы также можете найти способ сделать его не скопированным и пассивным, потому что ошибка будет происходить с вашими пользователями, и это будет раздражать.
Вот более свежий пример: вы проверили, насколько легко выбрать код пользователь должен копировать?
Kelsey Hightower попытался скопировать этот образец кода с StackOverflow в Google Cloud Следующее демо.
Он сделал это намеренно? Мир никогда не узнает. Тем не менее, он представляет собой борьбу кодировщиков, чтобы скопировать большие блоки текста на некоторые сайты документации. Убедитесь, что пользовательский интерфейс вашего сайта упрощает копирование больших блоков текста. Вы можете даже разбить эти блоки, чтобы объяснить их в кусках, делая их более доступными для копирования и понимания.
Загрузка...
