tech docs

Gov.uk One Togin Technical Documentation

Этот репо содержит документацию, чтобы помочь технологам в правительственных департаментах на борту в Gov.uk One Login. Он опубликован с использованием шаблона технической документации.

Внесение изменений в контент

Команда The Gov.uk One Login Technical Phist владеет этой документацией и несет ответственность за утверждение изменений контента. Это написано, чтобы ориентироваться на пользователя и соответствовать стандартам контента GDS, что означает следующее:

• Gov.uk Руководство по планированию, написанию и управлению контентом
• Руководство по стилю gov.uk
• Руководство по техническому стилю gov.uk
• Другие четкие принципы письма

Если вы работаете над gov.uk One Login, вам следует связаться с командой по написанию технических технологий для помощи с изменениями контента, если он не является небольшим и не влияет на поведение пользователей.

Небольшие изменения контента включают:

• Добавление разъяснений для улучшения понимания
• исправление образцов кода
• исправление сломанных ссылок или опечаток

Вы можете внести эти изменения самостоятельно, а затем запросить обзор технического писателя по запросу. Если вы не уверены, является ли изменение небольшое, свяжитесь с нами на нашем диви-техническом написании Slack Channel.

Внесение технических изменений

Команда оркестровки отвечает за обслуживание и эксплуатационное здоровье платформы Tech Docs. Вы должны проконсультироваться с ними для одобрения любых изменений в этом пространстве.

Примеры включают:

• Изменения в рабочих процессах Action GitHub
• Изменения в развертывании или построении AWS
• Обновления зависимости
• Обновления Ruby, которые не меняют контент

Предварительный просмотр изменения документации

Чтобы предварительно просмотреть любые изменения и дополнения, которые вы внесли в документацию в браузере, клонируйте это репо и используйте DockerFile в этом репо, чтобы запустить сервер Middleman на вашем компьютере без необходимости настраивания Ruby.

Эта настройка включена перезагрузка в прямом эфире, что означает, что ваши изменения будут применяться при редактировании файлов в каталоге Source. Единственное исключение из этого-если вы внесете изменения в config/tech-docs.yml , вы должны остановиться и перезапустить сервер, чтобы увидеть ваши изменения в предварительном просмотре. Вы можете остановить сервер с помощью Ctrl-C .

Запустите сценарий помощника:

./preview-with-docker.sh

Для построения контейнера Docker может потребоваться несколько минут, особенно если вы впервые запускаете сценарий. Когда сервер завершит загрузку, вы должны увидеть следующий вывод в терминале:

== View your site at " http://localhost:4567 " , " http://127.0.0.1:4567 "
== Inspect your site configuration at " http://localhost:4567/__middleman " , " http://127.0.0.1:4567/__middleman " /usr/local/bundle/gems/tilt-2.0.11/lib/tilt/redcarpet.

Внесение изменений в диаграмму

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

Вы можете отредактировать файлы draw.io в папке source/images/originals , установив и используя приложение Draw.io Desktop.

Используйте один файл draw.io на диаграмму.

Установка настольного приложения Draw.io

Запустите следующие команды, чтобы использовать настольное приложение Draw.io из командной строки.

 brew install --cask drawio
alias draw.io='/Applications/draw.io.app/Contents/MacOS/draw.io'

Редактирование и публикация диаграммы

Следуйте этим шагам:

1. Создать и изменить диаграмму, используя draw.io.
2. Сохраните файл drain.io в папку « source/images/originals .
3. Опубликуйте диаграмму как масштабируемую векторную графику (SVG).
4. Сохраните файл SVG в папку source/images .

Полезные команды

Обновите диаграмму:

 draw.io source/images/originals/top-level-technical-diagram.drawio

Создать версии SVG диаграмм и сохранить их в папке source/images/originals :

 draw.io -x -o source/images/top-level-technical-diagram.svg source/images/originals/top-level-technical-diagram.drawio

draw.io -x -o source/images/technical-flow-diagram.svg source/images/originals/technical-flow-diagram.drawio

Снижение технической документации gov.uk One Login

В этом репозитории используются Vale и GDS Tech Docs Linter.

Установка Linter на локальную машину

Вам нужно:

• Установите Homebrew
• Установите Vale

Снижение с вашим редактором кода

Многие редакторы кода предоставляют расширения или плагины для Vale, которые могут собирать ошибки при обновлении документации. Вам все еще понадобится установлен Vale на вашей местной машине.

Склад с интерфейсом командной строки Vale (CLI)

По умолчанию Vale должен запускать из того же каталога, что и этот файл конфигурации, если только флаг --config не предоставлен с пути. Чтобы запустить Linter, используя Vale CLI:

1. В окне терминала перейдите к своему репо.
2. Запустите vale sync , чтобы загрузить последний пакет Tech-Docs-Linter, и раскрипировать его в свой StylesPath указанный в вашем файле конфигурации.
3. Запустите команду vale . Чтобы прокинуть весь репо, или предоставить путь к каталогу, чтобы пронзительно, например, этот каталог: vale ./source/go-live

Обновление до последних технологических документов Linter.

Если новое правило добавлено в набор Tech Docs Linter, вы можете повысить пакет, используемый этим репо, когда вы будете готовы. Более поздняя версия набора правил может быть проверена и добавлена:

1. Создать ветвь.
2. Обновите номер версии пакета в файле конфигурации Vale.
3. Запустите vale sync , чтобы загрузить и разкапливаться в последнем пакете.
4. Запустите vale ./source чтобы проверить Линтер.
5. Исправьте любые изменения, которые новая набор правил (предпочтительно по одному совершению для каждого нарушения правила).
6. Поднимите пиар с последним номером версии в файле конфигурации Vale.

Нормы поведения

Пожалуйста, обратитесь к коду поведения alphagov .

Лицензия

Если не указано иное, кодовая база выпускается по лицензии MIT. Это охватывает как кодовую базу, так и любой пример кода в документации.

Документация © Crown Copyright и доступна в соответствии с условиями лицензии Open Paffice 3.0.