Если вы вдруг захотите слезть с Word’ов и прочих первобытых тулз и попытаетесь напрячь начальство на переход на работу с документацией как с кодом, то вот ключевые доводы которые будут полезны.

#DocsAsCode #en

Небольшой тизер будущей статейки. На выходе имеем SVG :3

#diagram #DocsAsCode

Покра руки доходят до написания нового ориджынал контента (а они дойдут, уже есть идея, но мало исходного материала), буду стараться накидывать вам интересного чтива. Сегодня в эфире довольно известный (в узких кругах) бложик про Docs as a Code (не путать с @docops / @docsascode в Телеграме, но тут тоже хорошо)

https://www.docslikecode.com/articles/

Всем хорошего рабочего дня 😺

#DocsAsCode #article #en

Docs Like Code запустили отдельную страничку с инструкциями по работе с Sphinx, Jekyll, Hugo, Continious Deployment док, Автотестам док и по работе с контентом в GH репах с, опять же, документацией:

https://www.docslikecode.com/learn/

P.S Поток контента чуть снизился из-за рабочего загруза, + понемногу пилю сайт-зеркало этого канала на котором будут статьи на английском ❤️

#DocsAsCode #SSG #en

Рассказ о том, как документация Redis Labs переехала (начала переезжать) на docs-as-code подход и заопенсорсила документацию и что из этого вышло.
https://www.docslikecode.com/articles/moving-agile-open-source-docs/

#article #DocsAsCode #en

https://habr.com/ru/post/414757/

#DocsAsCode #ru #article

Если вы имеете дела с доками которые в конечном счёте становятся html, то возможно эта тулза (html-proofer) вам подойдет.

Что умеет?

Картинки:

Проверяет img элементы:

- Все ли ваши изображения имеют alt-тэги
- Не нарушены ли ваши внутренние ссылки на изображения
- Отображаются ли внешние картинки
- Все ли ваши изображения содержат HTTP

Ссылки

Проверяет а, link элементы:

- Работают ли ваши внутренние ссылки
- Работают ли ваши внутренние хеш-ссылки (#linkToMe)
- Работают ли внешние ссылки
- HTTPS-ли ваши ссылки
- Включен ли CORS/SRI

Скрипты:

Проверяет `script` элементы:

- Работают ли ваши внутренние ссылки на скрипты
- Загружаются ли внешние скрипты
- Включен ли CORS / SRI

Favicon-ки:

- Валидны ли фавиконки

OpenGraph

- Валидны ли изображения и URL-адреса в метаданных OpenGraph.

HTML

- Валидна ли ваша HTML-разметка. Это делается с помощью Nokogumbo для проверки правильности разметки HTML5.

P.S пишу с мобильного клиента, сорри за верстку, таков путь

#DocsAsCode #tool #en

История о том, как команда Azure Sphere Security Services в качестве эксперимента перекатывалась с *перекрестился* SharePoint и Microsoft Word на Markdown и Git, и что из этого вышло

TL;DR

Кто бы мог подумать, что пересесть с квадратных колёс на круглые (no pun intended) всем понравится, и как следствие: "AS3 team considers the experiment incredibly successful"

https://caitiem.com/2020/03/29/design-docs-markdown-and-git/

#DocsAsCode #markdown #articke

Зашел я тут недавно в техрайтерские чатики и там снова про диаграммы.

Сам-то я предпочел бы хранить все их as a code, но есть и альтернативное мнение/решение.

На днях зарелизился абсолютно великолепный плагин для VS Code и наша редакция никак не могла пройти мимо.

Draw.io Integration! Исходники, естественно, открыты.

Фичи:

- Редактирование .drawio или .dio файлов как в редакторе Draw.io, так и голый XML (можно даже side by side).
- Редактирование .drawio.svg (svg!)
- По умолчанию используется офлайн версия Draw.io.
- Т.к Draw.io тоже опенсорсный продукт, он может быть и self-hosted, а это расширение поддерживает кастомный URL-адрес для вашего Draw.io инстанса .
- Темы

Когда VS Code'ный API для сторонних редакторов будет стабилен, автор обещает добавить поддержку редактирования .drawio.png

#diagram #DocsAsCode #en #vscode #tool

Познавательная "behind-the-scenes "-статейка от GitHub о том как они перезапускали docs.github.com и с какими проблемами сталкивались и как их решали.

https://github.blog/2020-07-02-how-we-launched-docs-github-com/

#article #markdown #DocsAsCode

Набрёл на DocForge – утилиту (пре-пуш тула) которая отслеживает, не устарели ли куски кода в документации. Никакой сложной настройки, пример конфигурации на скрине выше. Насколько я понял, в данный момент всё это дело еще не доступно, но товарищи просят к ним постучаться и предлагают попользовать их свежеиспеченную разработку или забукать демо.

#tool #en #DocsAsCode

Документация - важная часть любого продукта или услуги, ориентированной на клиентов. Без неё вашим клиентам нужна помощь, ваша служба поддержки изо всех сил пытается помочь пользователям, а ваша компания тратит деньги на недовольных клиентов, а не на создание новых продуктов.

Одна из самых больших проблем - создание качественной документации. Отношение к документации к как части вашего продукта заставляет всю производственную команду думать в первую очередь о пользователях. Отношение к документации как к коду понижает также планку вхождения и для команы разработчиков.

В этом выступлении редактор и технический писатель разбираются в том, как линтинг (моя излюбленная тема) может быть столь же важным для авторов, как и для разработчиков, и как методология «документация как код» может улучшить жизнь всех, кто работает над продуктом.

Это видеоподкасты в двух частях и одной текстовой:

Часть 1
Часть 2
Часть 3
Текстовая версия

#DocsAsCode #en #article

Небольшое, можно сказать, продолжение истории от Spotify про их Backstage и TechDocs плагин для него (не так давно как раз писал про это).

О чем?

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

Автор даёт 10 советов о том, как строить долгосрочные отношения с docs-as-a-code подходом, учит смотреть в будущее, как решать возникающие по ходу дела проблемы и рассказывает как смотреть на правильные метрики.

Читать

#DocsAsCode #tool #en

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

Читать: Why I Built My Own Shitty Static Site Generator

Bonus Track: Микро-история про создание спеллчекера в 84 году (хотя больше про стремительный прогресс технологий)

#SSG #DocsAsCode #en #testthedocs