В начале сентября стало ясно, что V1 Of Timeral будет готов к концу этого месяца. Это также означало, что вскоре мы объявим о нашем финансировании. С точки зрения документации, мы чувствовали, что важно координировать изменения таким образом, чтобы поддержать объявление. Как и в случае любого запуска продукта, мы надеялись создать немного шума и увидеть всплеск новых пользователей. Учитывая, что документация является одним из наиболее важных аспектов принятия новых пользователей, мы выделили для нас нашу работу.
В гору
С точки зрения нашей документации, мы столкнулись как минимум три задачи. Две из этих проблем были связаны непосредственно из того факта, что наши документы начинались как вилка документов от предшественника Themoral.
Первая задача заключается в том, что информация, которую мы унаследовали, отставала в полном описании возможностей и набора функций Themalal. Одна из причин этого заключается в том, что документация обычно предлагается вторичный уровень приоритетов. Несмотря на то, что временные теперь расставляют приоритеты документации, это не всегда было верно, откуда родовая как каденция.
Вторая проблема заключалась в том, что в системе, терминологии и SDK было много основных изменений в системе, терминологии и SDK. Еще в начале сентября многие из этих изменений еще не распространялись по всем документам. Так, Мало того, что не хватало информации, но и некоторая существующая информация была просто неверной.
Окончательная и самая большая проблема документирования временного – это то, что она в корне новой. Временный представляет другой подход к разработке приложений. Пользователи сталкиваются с набором знакомых терминов и концепций, но должны понимать их в совершенно новом контексте и ландшафте.
Выбирая путь
На высоком уровне есть две части для временного: бэкэнд и SDK на стороне клиента. Настройка, развертывание и эксплуатация временного бэкэнда для живой среды – это немалая задача. С другой стороны, действительно легко получить временную работу на местной машине в контейнере Docker. На самом деле, вы можете сделать это только с двумя командами терминала.
Маршрут Docker определенно упрощает запуск Backend, что означает, что большая часть трения для новых пользователей происходит от наших SDK ( Go , Java ) В то время как SDK предназначен для абстрагирования сложностей взаимодействия с API сервера, временный переворачивает много предвзятых представлений о современной разработке приложений на их голове. Документы SDK должны были сделать больше, чем просто приведены примеры использования. Им также нужно было показать «почему», чтобы позволить пользователю понять концепции, которые продвигает временные. Таким образом, мы рассказали о том, что мы могли бы реалистично достичь в течение этого периода времени, и все еще быть относительно эффективными.
Мы решили, что лучше всего сосредоточиться на новом пользовательском опыте. Мы хотели что -то, что позволило бы разработчику сразу же начать использование продукта, но также оставили их с пониманием значения, которое предоставляет временная предоставление. Мы хотели развивать это “Ага!” мгновенный
Мы начинали как можно больше с момента, пытаясь представить, как будет выглядеть идеальный новый пользовательский опыт. Затем мы определили как можно больше шагов, чтобы попасть туда. Оглядываясь назад, я бы утверждал, что нам удалось зафиксировать три идеи, которые, как мы думали, приведут нас к идеальному опыту. Надежда заключалась в том, что после того, как эти три идеи были объединены, они приведут к набору эффективных учебных пособий SDK для новых пользователей.
Snipsync
Это было примерно в это же время (в начале сентября), я тестировал инструмент Nodejs, который я создал, чтобы улучшить опыт создания и поддержания документации. Он загружает github Repos, скрещивает фрагменты кода, которые существуют между конкретными обертками комментариев, и записывает фрагменты в соответствующие обертки комментариев в файлах Markdown.
// @@@SNIPSTART unique-name-of-snippet
SomeFunc() {}
// @@@SNIPEND
Мы одолжили идею из Собственная версия Google Они используют для своих Google Cloud документация Анкет Концепция довольно проста, и я все еще удивлен, что не было существующего решения с открытым исходным кодом. Итак, мы сделали один!
Инструмент, который автоматизирует синхронизацию кода с документами из любого данного репозитория, имеет несколько ключевых преимуществ:
- Фрагменты кода в документации гарантированно будут работать, поскольку они непрерывно протестированы. Это также означает, что они могут быть надежно скопированы и вставлены в редактор пользователя.
- Мы точно контролируем, какие линии кода показаны, а также можем нацелиться на конкретную ветвь или коммит. Это отличная защита от ошибок, которая может быть введена в основную ветвь.
- Нам никогда не приходится совершать исходный код в документы. Код объединяется в отметки во время сборки. Это гарантирует, что код уже рассмотрен и одобрен из репо, в котором он находится.
Snipsync поступает с несколькими соображениями:
- Встроенный код должен тщательно просмотреть комментарии, структуру и иметь смысл в контексте документации. Например, если фрагмент кода поступает из рабочего репо, он может включать дополнительные переменные или вызовы функций. Они должны быть сведены к минимуму и оптимизированы, чтобы они не вызывали ненужную путаницу.
- Точно так же, как код должен быть оптимизирован для документов, документы также должны быть оптимизированы для кода. По сути, документы «управляются» и «определяются» базовым кодом. И если никто еще не придумал этот термин, я думаю, что кредит на «документацию, основанную на коде», должен быть направлен на наш глава продукта, Райланд Гольдштейн, когда он однажды днем поделился со мной этим прозрения.
Мы решили обнять Snipsync Поскольку проблемы, которые он ввел, были минимальными по сравнению со значением.
Snipsync на NPM
Шаблон репо
Теперь у нас был способ синхронизировать код с нашей документацией. Но откуда будет синхронизирован код? Мы знаем, что пользователи, скорее всего, захотят просмотреть исходный файл и относительный путь файла фрагмента кода для дополнительного контекста. Они также могут клонировать репо и попытаются запустить образец.
На самом деле у нас уже были репозитории образцов кода для Go SDK и Java Sdk Анкет Хотя мы хотели увидеть больше образцов, в каждом репозитории уже было немало. Но мы обнаружили, что общие репозитории выборки, как правило, имеют две проблемы, которые сделали их менее идеальными для синхронизации с документами.
- Несмотря на удобное, колокат множественные образцы в одном репо гораздо менее доступно по сравнению с хранением образцов в автономных репо.
- В общих репозиториях выборки труднее сохранить идиоматический характер любого языка и отражать функциональность любого образца на разных языках.
Таким образом, для каждого из образцов приложений, которые мы планировали использовать для управления нашей документацией, мы создали соответствующий шаблон. Эти шаблоны могут быть легко скопированы, построены и запускаются за считанные минуты.
- Go шаблон денежных переводов репо
- Иди привет мировой шаблон репо
- Java Money Transfer Template Repo
- Java Hello World Template Repo
Учебник
Поскольку цель наших изменений документации состояла в том, чтобы помочь с приобретением новых пользователей, мы решили стремиться к стилю документации «учебник». Первые итерации были направлены на развитие и замену существующих страниц SDK «быстрый старт», которые поддерживали статус -кво и напечатали «Привет, мир!» к консоли. Как вы уже догадались, этого маршрута недостаточно, чтобы показать пользователям реальные временные предложения.
Как только стало ясно, что стандартный подход не собирается его сократить, мы привлекли нашего соучредителя и генерального директора Maxim Fateev. Мы попросили его продемонстрировать нам демонстрацию, которую он обычно использует, чтобы представить инженеров с временным в первый раз. Сценарий представляет собой денежный перевод с одного банковского счета на другой, а во время демонстрационной максима демонстрируется, что произойдет, если один из шагов в переводе не удастся. Образец денежного перевода был отличным способом ввести ценности временной. Ибо, если вы понимаете последствия потери денег из неудачной финансовой транзакции, несколько ценностей временных становятся немедленно очевидными:
- Состояние запуска кода поддерживается даже благодаря сбоям аппаратного обеспечения, сбоя сервера и отключения сети.
- Существует глубокая видимость в состоянии выполнения кода из коробки через CLI или пользовательский интерфейс.
- Функциональные вызовы поставляются с автоматическими и повторными и настраиваемыми тайм -аутами.
- Ошибки могут быть горячими при запуске кода.
Для кого -то, кто является новым для временного, аттракцион не приходит от использования SDK для печати «Hello World!». Вместо этого это происходит из-за того, что он является неотъемлемым преимуществами, которые временные предложения, запустив симуляции с использованием предварительно созданного приложения.
Это направление, в котором мы решили отправить новых пользователей. Если пользователь может обернуть свои головы вокруг значения, которое височно привносит в свое приложение прямо из коробки, то тратить время и энергию на настройку приложения и изучение SDK становится не блокированным.
Проверьте эти готовые учебники и убедитесь сами!
- Go: Запустите свое первое временное приложение
- Java: запустите свое первое временное приложение
Следующие шаги
В Temporal мы понимаем, что наша документация играет очень важную роль в опыте наших пользователей. И чтобы доставить наши документы в состояние мирового класса, у нас перед нами много работы. В ближайшем будущем мы рассмотрим комплексное путешествие через нашу документацию и то, как мы можем предоставить лучший опыт для каждого пользователя. Чтобы проверить любое направление, которое мы рассматриваем, мы будем взаимодействовать с сообществом, чтобы услышать, что вы думаете, и помогать нам набрать вещи. Любой пользователь может Запланируйте 15 -минутную сессию обратной связи Со мной прямо! Мы также будем подготовиться к всем новым и захватывающим функциям в наших размещенных облачных предложениях, которые позволят всем разработчикам создавать непобедимые приложения.
Оригинал: “https://dev.to/temporalio/the-process-of-creating-sdk-tutorials-for-new-users-3cmh”