На этой странице содержится подробная информация о проекте технического написания, принятом для участия в Google Season of Docs.
Краткое описание проекта
- Организация с открытым исходным кодом:
- Национальный ресурс сетевой биологии (NRNB)
- Технический писатель:
- Прубхтей_9
- Название проекта:
- Создавайте пользовательскую документацию для SynBioHub и разрабатывайте учебные пособия для конкретных случаев использования.
- Длина проекта:
- Стандартная продолжительность (3 месяца)
Описание проекта
Абстрактный
Пользовательская документация предназначена для оказания помощи конечным пользователям в использовании продукта или услуги. Хорошая пользовательская документация очень важна, поскольку она дает пользователям возможность узнать, как использовать программное обеспечение, его функции, советы и рекомендации, а также решать распространенные проблемы, возникающие при использовании программного обеспечения. Это также снижает стоимость поддержки и является частью фирменного стиля продукта, т.е. хорошая пользовательская документация — признак здорового продукта и команды разработчиков. Без хорошей пользовательской документации пользователь может не знать, как эффективно и результативно выполнять действия, упомянутые выше. Пользовательская документация может сыграть решающую роль в обеспечении успеха продукта, поскольку отличная коммуникация есть и всегда будет в основе любого бизнеса или продукта, а хорошая документация просто берет эту коммуникацию и помещает ее в управляемую структуру, к которой каждый может получить доступ для достижения успеха. SynBioHub — это хранилище проектов синтетической биологии. Он доступен как в виде общедоступного веб-сайта, так и в виде программного обеспечения с открытым исходным кодом. SynBioHub использует открытый язык синтетической биологии (SBOL), стандарт с открытым исходным кодом для представления генетических проектов, а также позволяет совместно использовать части дизайна из файлов GenBank и FASTA. SynBioHub можно использовать для публикации библиотеки синтетических деталей и проектов в качестве услуги, для обмена проектами с соавторами и для локального хранения проектов биологических систем. Доступ к данным в SynBioHub можно получить через HTTP API, Java API или Python API, где их затем можно интегрировать в инструменты САПР для создания генетических проектов. SynBioHub содержит интерфейс, позволяющий пользователям загружать новые биологические данные в базу данных, визуализировать части ДНК, выполнять запросы для доступа к нужным частям и загружать SBOL, GenBank, FASTA и т. д. На сайте также доступны различные исследовательские работы и некоторые учебные пособия. Интернет, например: 1. https://pubs.acs.org/doi/abs/10.1021/acsynbio.7b00403 2. https://pubs.acs.org/doi/abs/10.1021/acssynbio.0c00056 SynBioHub имеет некоторую документацию, о которой можно говорить только по API, тогда как по графическому интерфейсу документации нет.
Текущее состояние документации:
В настоящее время пользовательская документация доступна по адресу: «https://synbiohub.github.io/api-docs/#about-synbiohub». Это всего лишь документация по API, а документации по графическому интерфейсу не существует, которая могла бы помочь пользователю перемещаться по репозиторию проектов. Кроме того, документация API также нуждается в небольшом обновлении, включая некоторые конкретные темы, такие как устранение определенных проблем, с которыми может столкнуться пользователь. Хотя организация записала несколько обучающих видеороликов, например, здесь. На SynBioHub действительно не существует письменной пользовательской документации, которая могла бы помочь пользователю.
Почему предлагаемая вами пользовательская документация лучше существующей? Я буду создавать документацию по графическому интерфейсу с нуля, используя github и уценку, как предложил наставник г-н Крис Майерс. Предлагаемая пользовательская документация будет структурирована таким образом, чтобы улучшить и обеспечить эффективность, последовательность и спокойствие для любого конечного пользователя. Он будет содержать письменные руководства и связанные с ними изображения, а также инструкции и объяснения того, как использовать каждую функцию симулятора SynBioHub с открытым исходным кодом. В ходе обсуждений с г-ном Майерсом также было решено, что документация по API будет объединена с GUI и будет содержать 6 разделов, из которых 6-й раздел будет необязательным. Разделы упоминаются следующим образом: 1. Введение 2. Инструкции по установке а) Из готового образа б) Из исходного кода в) Конфигурация NGINX 3. Инструкции пользователя а) Подробные инструкции по использованию каждой функции графического интерфейса б) Учебные пособия для распространенных случаев использования 4 . Документация по API — раздел «Конечные точки» 5. Документация по плагину 6. Устранение неполадок и будущие ссылки.
Часть-1:
В этом разделе пользователям будет предоставлено подробное введение и различные учебные пособия по SynBioHub.
Часть-2:
В этом разделе описаны различные способы, с помощью которых пользователь может установить программное обеспечение с открытым исходным кодом, используя различные методы, а именно: а) Из готового образа б) Из исходного кода в) Конфигурация NGINX
Часть-3:
Это самая важная часть документации, которая отнимет большую часть времени. Здесь каждая мельчайшая деталь будет добавлена в контексте графического пользовательского интерфейса. Как упоминалось выше, в этом разделе будут рассмотрены в основном две проблемы: подробные инструкции по использованию каждой функции графического пользовательского интерфейса и некоторые учебные пособия для распространенных случаев использования.
Часть-4:
Как упоминалось выше, для создания документации этой части будет использоваться slate. В этот раздел будут включены следующие конечные точки: 1. Конечные точки пользователя 2. Конечные точки поиска 3. Конечные точки загрузки 4. Конечные точки загрузки 5. Конечные точки отправки 6. Конечные точки разрешений. 7. Редактирование конечных точек 8. Конечные точки вложений 9. Конечные точки администрирования
Часть-5:
В этот раздел будет включена документация по плагину, которая уже присутствует в старой документации SynBioHub. Этот раздел будет разделен на два раздела, а именно: спецификация и реализация плагина. Часть 6: [Необязательно] Этот раздел будет включать очень распространенный список ошибок, с которыми сталкиваются пользователи, а также некоторые инструкции по устранению неполадок. В ходе обсуждения с г-ном Майерсом было решено, что этот раздел можно объединить с вводным разделом, если он не станет слишком длинным. Анализ. У нас с мистером Майерсом состоялся разговор о том, как обновить существующую документацию, а также написать новую для графического интерфейса. В ходе этих нескольких разговоров мы сформулировали базовый макет новой документации, о которой упоминалось выше, а приблизительные сроки реализации приведены на странице 5 ниже. Согласно обсуждению, я буду использовать github и уценку для создания документации для каждого раздела, кроме части 4 документации, в которой будет использоваться slate. Slate: — Slate помогает создавать красивую, умную и отзывчивую документацию по API. Slate — это инструмент на основе Ruby, который создает великолепный трехпанельный статический сайт документации API из набора файлов уценки. Он был создан разработчиком Робертом Лордом в 2013 году, когда он был 18-летним стажером в компании Tripit, занимающейся разработкой программного обеспечения для путешествий. Тогда он убедил своего босса позволить ему открыть исходный код проекта, а остальное уже история. Он имеет следующие особенности: • Чистый, интуитивно понятный дизайн. В Slate описание вашего API находится в левой части документации, а все примеры кода — в правой. Вдохновлен документами API Stripe и PayPal. Slate адаптивный, поэтому отлично смотрится на планшетах, телефонах и даже в печати. • Все на одной странице. Прошли те времена, когда пользователям приходилось просматривать миллион страниц, чтобы найти то, что они хотели. Slate помещает всю документацию на одну страницу. Однако мы не пожертвовали связностью. По мере прокрутки хэш вашего браузера будет обновляться до ближайшего заголовка, поэтому ссылка на определенный раздел документации по-прежнему будет естественной и простой. • Slate — это просто Markdown. Когда вы пишете документы с помощью Slate, вы просто пишете Markdown, что упрощает редактирование и понимание. Все написано в Markdown — даже примеры кода представляют собой просто блоки кода Markdown. • Напишите примеры кода на нескольких языках. Если ваш API имеет привязки к нескольким языкам программирования, вы можете легко добавить вкладки для переключения между ними. В своем документе вы сможете различать разные языки, указав название языка в верхней части каждого блока кода, как в случае с GitHub Flavored Markdown. • Готовая подсветка синтаксиса для более чем 100 языков, настройка не требуется. • Автоматическая плавная прокрутка содержания в крайнем левом углу страницы. При прокрутке отображается ваше текущее положение в документе. Это тоже быстро. Мы используем Slate в TripIt для создания документации для нашего нового API, где в нашем оглавлении содержится более 180 записей. Мы позаботились о том, чтобы производительность оставалась превосходной даже при работе с большими документами. • Позвольте пользователям обновлять вашу документацию за вас. По умолчанию ваша документация, созданная с помощью Slate, размещается в общедоступном репозитории GitHub. Это не только означает, что вы получаете бесплатный хостинг для своих документов с помощью GitHub Pages, но также позволяет другим разработчикам легко отправлять запросы на извлечение ваших документов, если они обнаруживают опечатки или другие проблемы. Конечно, если вы не хотите использовать GitHub, вы также можете разместить свои документы в другом месте. • Поддержка RTL Полная раскладка справа налево для языков с письмом справа налево, таких как арабский, персидский (фарси), иврит и т. д. Verdict Slate — одно из самых мощных программ с открытым исходным кодом для создания документации, согласно обсуждениям с моим наставником г-ном Крис Майерс: Для части 4 я буду использовать Slate, а для остальных частей — GitHub и Markdown. Более подробный обзор документации обсуждается в разделах ниже. Структура предлагаемой документации Я создал структуру для Руководства пользователя SynBioHub, которую можно найти на странице 2. Эта структура принята и уже изменена г-ном Майерсом. Цели проекта 1. Реструктуризация документации. 2. Обновите документацию, чтобы она соответствовала современным версиям SynBioHub. 3. Удалите устаревшую информацию. 4. Перепишите пользовательскую документацию, чтобы ее было легче понять. 5. Включите краткий раздел предварительных требований в документацию для новых участников, чтобы улучшить их базовое понимание основных биологических концепций и интерфейса SynBioHub.