Ни дня без велосипеда 🤷‍♂️

Некто Томас Аллмер, основатель Open Web Components выпустил MDJS, вариант Markdown, который позволяет разработчикам включать код JavaScript в документацию на Markdown. Вот тут еще статейка.

Я, скорее всего, чего-то просто не понял, но в моей вселенной уже существует MDX.

#markdown #en #tool

Лучшая. Getting. Started. Дока. Эвэр.

https://stripe.com/docs/payments/integration-builder

Будьте как Stripe.

#example #en

Экосистема vs Среда обитания.

В этой статье идет речь о том, что сравнение программных «экосистем» - странный способ выбрать инструмент для документации. Автор предлагает несколько иначе подходить к выбору инструментария.

https://ddbeck.com/static-site-ecosystems/

#article #en

Нужно написать релиз ноуты? Чейнджлоги? А вдохновения нет?

А может их никто и не читает вообще и можно написать туда абы что?

Ответы на эти и еще многие другие вопросы в прекрасной статье про искусство написания релиз ноутов:

https://uxdesign.cc/the-art-of-writing-great-release-notes-6607e22efae1

#cnahgelog #en #uiux

Гитлаб предлагает пополнить свое (ну, то есть ваше) портфолио опенсорс контрибьюшнами в документацию и предоставляет список простеньких ишшью которые хорошо бы было пофиксить.

В довесок делятся перечнем "хороших первых контрибьюшнов" в качестве образца.

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

#vacancy #resource #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

Words To Live By:

https://twitter.com/santiwilly/status/1257779891711475716

#example #en

Проклятие знания

Совет Стивена Пинкера (из Гарварда, если вам вдруг важно).

Если ты что-то знаешь, то автоматически думаешь, что другие тоже в курсе. Но это не так — и это мешает вам писать нормально. У тебя в голове есть контекст, знания, опыт — а у читателя всего этого нет, поэтому иногда вы говорите на разных языках. Если вас хоть раз просили объяснить «будто мне 5 лет» — то это из-за «проклятия знания».

Как с этим бороться: дайте прочитать текст кому-то ещё. Например, редактору. Или маме. Другой человек легко найдёт все моменты, которые не понимает, а вы сможете их переписать.

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

Сам-то я предпочел бы хранить все их 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

*вдох*
ReadMe Flavored Markdown
*выдох*

https://docs.readme.com/rdmd/docs

#tool #markdown

Небольшой текст с рассуждениями о том, когда лучше публиковаться (документацию), когда уже написано много, или когда написано мало, и что вообще такое "много", "достаточно", и "мало".

https://ddbeck.com/how-small-is-enough/

#resource #article #en

Такой интересный год для Microsoft-опенсорса выдался:

- Microsoft забирает назад свои слова про опенсорс: "Microsoft was on the wrong side of history when open source exploded at the beginning of the century",
- Улучшает поддержку Linux в WSL2, позволяя запускать Linux-GUI приложения прямо в винде,
- Чинит трансляцию GPU вызовов в ядро, добавляет GPU-ускорение и DirectX (!) в WSL2,
- Выпускает нормальный (опенсорсный!) терминал.

И наконец-то про документацию:

Анонсированный в 2019 Fluid Framework представляет из себя "конструктор лего" для документов, такой себе Google Docs, если хотите. Я больше это вижу подвижкой в сторону Notion-изирования, больше никакого создания и сохранения и пересылки документов. К 2020 практически все офисные пакеты ушли от парадигмы файлов и полностью окунулись в коллективное создание всего и вся в "облаке". Так вот, теперь это всё опенсорсное, весь Fluid Framework с недели на неделю появится на гитхабе и предположительно там всё на TypeScript, и судя по всему, это интересный фундамет for what's to come.

Почитать больше можно тут.

#article #en

А ещё у Notion персональный план стал бесплатным и без ограничений на блоки. Теперь у вас ровно 0 причин не попробовать эту приятную тулзу.

Yet Another Markdown IDE - Obsidian. На этот раз чуваки позиционируют себя как Базу Знаний, но без "облачных" примочек, живёт это дело поверх локальной папочки с .md файликами. Вообще такой подход мне близок, это сродни покупки игр на физических носителях, да и вообще довольно таки любопытно и фичасто.

#tool #en #markdown #knowledgemanagement

Gatsby запустил бенчмарк willit.build, в котором можно посмотреть и даже посчитать время билда сайта с разным объемом страниц и с разных контент-провайдеров. Не зря чувакам кучу денег вдонатили, развиваются быстрее всех. Пора копать в его сторону, будет не самым бесполезным знанием в арсенале техрайтера/докопса.

#SSG #tool

Пятничного чтива пост.

Вы када-нить задумывались, как проводились и документировались исследования до того, как был изобретён LaTeX?

Очень крутецкий тред именно про это:

Тред на threader: https://threadreaderapp.com/thread/1262489387767480322.html

Оригинальный тред в Twitter'е: https://twitter.com/iraphas13/status/1262489387767480322

#LaTeX #en #article

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

Эта статья от StackOverflow о том как писать техническую спецификацию:

https://stackoverflow.blog/2020/04/06/a-practical-guide-to-writing-technical-specs/

#article #en #resource

Думал видел уже все цмс-ки для статических сайтецов. А вот тут еще одна попалась на глаза.

Typemill - flat-file CMS для преимущественно текстовых сайтов: хендбуки, мануалы, документация. Есть темы, плагинчики и всё опенсорсное.

Звёзд с неба не хватает, но выглядит прилично, есть четкий роадмеп, подойдет для быстрой развертки или для небольших проектиков, если у вас нет непереносимости PHP или Vue.js.

#SSG #tool #en #markdown