Если вы вдруг захотите слезть с 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

В последнее время вижу все больше и больше пользователей и советчиков (и без того популярного) MkDocs, поэтому вот вам два гайда, которые might come in handy на старте, так сказать:

1. Getting started with Material MkDocs — установка, кастомизация, публикация и траблшутинг.
2. Deploying MkDocs with Material theme to Netlify — название говорит само за себя

#markdown #DocsAsCode #SSG

👅 Языки:

#ru | #en

👷 Карьера:

#career — советы и всемозможные статьи о карьере техписателя
#conference — техписательские конференции, их записи и заметки
#resources — ресурс для саморазвития
#article — полезная статья, которая учит чему-то клёвому, что позволит стать более лучшим писателем
#vacancy — интересная вакансия или что-то связанное с наймом
#video — видео, видос, видосичек, видосюлька. И подкасты!
#book — книга/хендбук
#courses — курсы, программы для технических писателей

🛠 Технологии:

#tool — полезная утилита/приложение
#changelog — все о чейнджлогах, примеры, правила
#markdown — все о языке разметки Markdown
#reStructuredText — все о языке разметки reStructuredText
#asciidoc — все о языке разметки asciidoc
#LaTeX — все систему набора и вёрстки и язык разметки LaTeX
#ide — среды разработки и все что с ними связано
#vscode — все о Visual Studio Code, настройка, плагины, хитрости
#SSG — JAMStack, генераторы статических сайтов, Hugo, Jekyll, Antora, etc.
#testthedocs — тестирование документации, линтинг
#API — про документирование API, примеры, лайфхаки, подсказки
#diagram — про диаграммы (много про diagrams as a code), mermaid, UML
#screenshot — все про скриншоты, утилиты, сервисы и красивенькие фотоснимки экрана
#ai — про GPT, GitHub Copilot и прочее, где ИИ помогает нам писать

🧺 Общее:

#tonevoice — о правилах общения в документации
#language — что-то конкретно о языке, в основном английский
#legal — юридическая документация, лицензии
#styleguide — все о стилях и правилах
#DocsAsCode — все про подход к документации как к коду
#example — примеры документации (хорошие и плохие)
#uiux — интерфейсы, текст в интерфейсах, пользовательский опыт
#knowledgemanagement — менеджмент знаний, хранилища, тулзы, техники, советы и наблюдения
#versioning — про версионирование
#accessibility — все об аксессебилити в документации
#checklist — чеклист/шпаргалка
#vintage — винтажная документация, старые компьютеры, софт, техника, игры
#visual — про визуальную составляющую документации
#metrics — все о метриках документации
#random — что-то совсем косвенно относящееся к техписательству, юморески

Предлагайте новые хэштеги в комментариях!