Советы и усвоенные уроки

Вступление

Мы разработали и опубликовали надстройку Google Doc с открытым исходным кодом под названием Referencer, которая помогает автоматизировать перекрестные ссылки для рисунков, таблиц и заголовков разделов примерно за две недели.

Я узнал кое-что новое из этого короткого, но увлекательного опыта и хочу поделиться с другими, кто заинтересован в создании надстроек для продуктов и инструментов GSuite (например, Google Docs and Sheets).

Мотивация

Я много пишу, индивидуально или совместно, как часть моей работы. С одной стороны, мне нравится, как Latex автоматизирует вещи, но мне не нравится писать в большинстве инструментов на основе Latex. Overleaf упрощает совместное письмо в латексе, но я все еще считаю, что его пользовательский интерфейс не идеален.

С другой стороны, мне очень нравится писать в Google Docs, но я ненавижу вручную настраивать в Google Docs такие вещи, которые можно легко автоматизировать в Latex, например перекрестные ссылки и цитаты. В результате я хочу продолжать получать удовольствие от написания в Документах Google, но при этом автоматизировать некоторые вещи, как если бы я делал это при использовании Latex. Я пробовал все существующие надстройки, которые помогают с перекрестными ссылками на GSuite Market - они либо достигли слишком крошечной части (например, перекрестные ссылки только для заголовков разделов), либо менее интуитивно понятны, чем ожидалось (например, не понимают, как использовать его после нескольких минут чтения).

Когда с марта этого года все переместилось в Интернет из-за пандемии, я уже не мог помогать студентам в своей исследовательской лаборатории, как раньше. Несколько наших исследовательских проектов были почти остановлены. Поэтому я решил заняться чем-то другим с двумя своими учениками в надежде, что это поможет им расти, а также принесет пользу другим - разработка интуитивно понятного дополнения Google Doc, которое обеспечивает автоматизацию перекрестных ссылок .

Планирование и дизайн

У нас нет месяца или двух, чтобы поработать над этим - у меня есть классы, которые нужно преподавать, статьи, которые нужно писать, и мучительная работа по обслуживанию; у моих студентов-исследователей есть набор онлайн-курсов, которые нужно пройти, и, вероятно, им нужно заняться чем-то большим, чем то, что у меня на тарелке. Мы дали нам около двух недель на выполнение этой задачи, поэтому тщательное планирование является ключом к нашему успеху. Вот план, который я составил:

Вот три ключевых урока, которые я извлек из нашего первого спринта по изучению JS / Google App Script / Google Doc API:

1. Изучить Javascript (JS) за 3 дня возможно (в некоторой степени). JS необходим для разработки надстроек для Google Docs. У меня никогда раньше не было возможности глубоко погрузиться в JS, и мой трехдневный опыт обучения говорит, что можно освоить JS за 3 дня, чтобы достичь уровня, достаточного для выполнения такого небольшого проекта, как этот. Вот стратегия, которую я использовал, чтобы сделать свое трехдневное обучение максимально эффективным:

  • Изучение синтаксиса JS с помощью Code Academy: мне нравится, как Code Academy делает изучение синтаксиса интерактивным. Я не просматривал их руководство шаг за шагом - вместо этого я читаю инструкции и часто перескакиваю, чтобы прочитать их решения как отработанные примеры. Я не платил за подписку на Code Academy, поэтому у меня не было доступа к их руководствам по решению проблем - я не думаю, что они вообще необходимы для достижения моей цели.
  • Сгибание мускулов для решения проблем с помощью leetcode: я практиковал от пяти до семи навыков решения проблем с использованием JS в онлайн-инструменте оценки leetcode по некоторым из выбранных тем, таких как стек, хеш-таблица и возврат. Это не для подготовки к собеседованию :) Мне нравится, как leetcode предоставляет интерактивный онлайн-инструмент для судейства для решения некоторых хорошо известных проблем. Вы можете подумать, что в этом нет необходимости - я согласен, но они помогли мне попрактиковаться в синтаксисе, который я выучил, и сделали изучение синтаксиса менее утомительным.
  • Решить несколько простых проблем в контексте: я решил ряд простых проблем в контексте взаимодействия с Документом Google через его API, таких как сбор всех абзацев и их распечатка по отдельности, а также сбор всех закладок. . Самой сложной задачей, которую я решил сам, было собрать все ссылки, включая тексты и URL-адреса, что оказалось очень полезным для этого проекта: Нам нужно собрать все объекты ссылок, которые связаны с закладками, что лучше всего решить. рекурсией .

2. Структуру Google Doc следует рассматривать как объектную модель документа (DOM). Понимание DOM критически важно для взаимодействия с Google Docs через его API.

Например, вы можете легко добавить еще несколько абзацев в документ Google:

var body = DocumentApp.getActiveDocument().getBody();
body.appendParagraph('Paragraph 1');
body.appendParagraph('Paragraph 2');
body.appendParagraph('Paragraph 3');
body.getParagraphs(); // return a list of Paragraph objects

Тело документа - это четко определенный класс с набором удобных методов. .getParagraphs() - один из этих методов, он возвращает список объектов Абзац.

3. Будьте готовы к грубой отладке в Google App Script (GAS). GAS - это платформа сценариев для разработки легких приложений, таких как надстройки для Google Docs или Sheets:

Если у вас есть опыт веб-разработки, вы можете больше полагаться на Chrome или Firefox DevTools, различные точки останова и трассировку кода, но меньше на использование console.log() для распечатки материалов во время тестирования и отладки.

Когда вы работаете над надстройкой для Google Docs, мне сложно оставить онлайн-среду GAS для локального кодирования, так как мне нужен GAS для тестирования и отладки. В среде GAS очень мало помогают Chrome или Firefox DevTools. Хотя вы все еще можете использовать один или два типа точек останова в GAS, вам нужно использовать Logger.log() для вывода большого количества материала для тестирования и отладки (Примечание: Logger.log() эквивалентно console.log() для GAS). Я попытался настроить локальную среду программирования для GAS с помощью CLASP, но в конце концов отказался - если свободное владение инструментом занимает слишком много времени, это больше не является для меня достойным вложением в контексте этого проекта.

Изучите существующие продукты и поведение пользователей

Мы изучили, как существующие надстройки Google Doc обеспечивают перекрестные ссылки, а также как обычные авторы пишут в Google Docs. Если вы никогда раньше не слышали о термине «перекрестная ссылка», вот его определение:

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

Когда дело доходит до Google Doc, мы хотим достичь следующего:

  • автонумерация рисунков, таблиц и заголовков разделов
  • синхронизировать перекрестные ссылки любых рисунков, таблиц и заголовков разделов

Вот один ключевой урок, который я извлек из нашего второго спринта исследований и дизайна:

Простые подходы к достижению намеченной функциональности могут не обеспечить наилучшего взаимодействия с пользователем. В контексте этого проекта простым способом достижения автоматической нумерации и синхронизации перекрестных ссылок является использование URL-адресов - вставка URL-адреса для каждого заголовка рисунка / таблицы / раздела (например, #gray-cat) и вставка соответствующей ссылки в ссылку на этот URL). Этот подход технически легко реализовать с точки зрения программирования, и он используется существующими надстройками с перекрестными ссылками.

Просматривая комментарии к существующим надстройкам и спрашивая других авторов, которые часто пишут в Документах Google, мы обнаружили, что узким местом этого подхода является ручная вставка URL-адресов, начинающихся с #, и связывание их в ссылочных текстах. Такой подход непривычен для менее технически подкованных пользователей. Кроме того, если в одном документе много рисунков или таблиц, это может стать довольно утомительным. Обобщая информацию и отзывы, мы решаем не применять этот подход, несмотря на то, что его легко реализовать с точки зрения программирования.

В рамках отдельной попытки изучить API и встроенные функции Документов Google мы обнаружили, что:

  • Заголовки разделов могут быть преобразованы в заголовки с согласованными стилями, что рекомендуется в Документах Google.
  • Закладки легко добавлять и ссылаться на них из любого места в одном документе Google.

Основываясь на этих двух встроенных функциях, мы можем обойти узкое место, связанное с использованием только URL-адресов, и обеспечить лучший пользовательский интерфейс для перекрестных ссылок - нет необходимости вставлять набор странных URL-адресов для рисунков / таблиц / заголовков разделов. . Кроме того, добавление ссылки на закладку сделано для удобства Google.

PS: Мы не осознавали, что это значительно труднее достичь с помощью программирования, пока не начали нашу реализацию - это рассматривается в следующем разделе.

Внедрение и тестирование

Мы интенсивно кодируем около недели, вовремя завершая внедрение и тестирование. Вот два ключевых урока, которые я извлек из нашего спринта внедрения и тестирования:

1. Установите структуру кода в соответствии с ожиданиями публикации с самого начала. Структуру надстройки GSuite можно обобщить и проиллюстрировать следующим образом:

Каждой надстройке GSuite требуется манифест appscript.json, который содержит определенные сведения о скрипте и его работе, такие как область действия OAuth и имя надстройки. Остальные gs файлы, перечисленные на рисунке выше, не требуются, но используются как часть общей структуры многих надстроек GSuite с открытым исходным кодом:

  • Основной файл обрабатывает взаимодействие между пользователем и вашим дополнением. Основной файл вызывает функции, определенные в файле обработчика ошибок, для обработки ошибок и в других gs файлах для помощи при взаимодействии.
  • Обработчик ошибок определяет все возможные реакции на поведение пользователя, которое может привести к ошибкам при выполнении кода вашей надстройки.
  • Вы можете увидеть, что во многих надстройках есть кнопка «Справка», которая приводит к подсказке со ссылками и кратким вступлением - не тратьте время на настройку пользовательского интерфейса для него, так как это выполняется автоматически во время публикации. процесс. В руководстве нет четких инструкций по созданию этой кнопки «Справка», и мы потратили некоторое время на то, чтобы разобраться с ней, пока не выяснили, о чем она:

2. Вам часто потребуется создавать собственные классы поверх классов, определенных в Google API. В контексте этого проекта нам нужно собрать все закладки в Google Doc - вы можете собрать все закладки в виде списка, используя Google Docs API , но эти закладки не помещаются в список в порядке их появления в документе, что вообще не объясняется в руководстве по API. Во время тестирования мы также обнаружили, что нам нужно вставить пакет новых закладок, чтобы заменить старые, вставленные пользователями, чтобы добиться автоматической нумерации и обновления текста. В противном случае летают всевозможные странные ошибки. Вот наш окончательный дизайн нового класса закладок с именем BookmarkObj для обработки всех возможных обновлений перекрестных ссылок:

Публикация на GSuite Market

В целом, я многому научился во время спринта публикации этого приложения на GSuite Market - я был незнаком с процессом, и я не чувствую, что процесс описан так ясно, как это могло бы быть в руководстве. Вот три основных урока, которые я извлек:

1. Разберитесь с логистикой как можно раньше. Для публикации требуется набор ресурсов (например, логотипы и снимки экрана) и веб-сайт с необходимой информацией (например, политикой конфиденциальности и условиями обслуживания). Кроме того, необходимо подтвердить домен сайта. Все эти работы можно выполнять в параллельном потоке, если вы работаете в команде из двух и более человек. Даже если вы работаете один, полезно подумать об этих задачах заранее.

2. Отправьте экран согласия OAuth на одобрение как можно раньше. Проверка надстройки для публикации G Suite Marketplace - это двухэтапный процесс. Проверка экрана согласия OAuth - это первый шаг, который может занять несколько дней или недель, а также несколько раундов отказа и запроса дополнительной информации. Экран согласия OAuth позволяет пользователям выбрать, хотят ли они предоставить доступ к своим личным данным, и дать им ссылку на условия обслуживания и политику конфиденциальности:

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

3. Работайте с максимально возможным количеством типов поведения пользователей, особенно с теми, которые могут приводить к ошибкам. Если вам не удастся исправить эти ошибки, ваше дополнение может быть отклонено без обратной связи. Отказ без объяснения и обратной связи может расстраивать. Наше дополнение было отклонено один раз.

Когда вы имеете дело с поведением пользователей, которое может привести к ошибкам, последнее, что вы хотите сделать, - это отправить настроенное предупреждение об ошибке с помощью try & catch. Если вы это сделаете, очень вероятно, что ваше дополнение будет отклонено для публикации. Обобщая всю информацию, которую мы смогли найти в Интернете, лучше всего запретить пользователям запускать ваш дополнительный код и дать им подсказку с объяснениями любого поведения, которое может привести к ошибкам. Приглашаем вас проверить то, что мы сделали, на примере одобренных надстроек.

И последнее, но не менее важное: наше дополнение можно найти по адресу:

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

Связанные истории



Создание с помощью React для всех платформ: лучшие фреймворки и инструменты
5 рекомендуемых фреймворков и инструментов, которые помогут вам использовать React для сборки для всех платформ. blog.bitsrc .io





Принципы кода, которым должен следовать каждый программист
ЯГНИ, Закон Деметры, единой ответственности и другие полезные принципы для лучшего программирования. blog.bitsrc.io





10 супер полезных приемов для разработчиков JavaScript
Полезные приемы Javascript, которые вы могли пропустить. blog.bitsrc.io