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

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

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

#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

Есть в английском такой термин как weasel words, что на нашенском будет "обтекаемые выражения", это ни к чему не обязывающие слова, эдакая намеренная двусмысленность. Вы уже наверное поняли к чему я веду. В нашей работе не стоит злоупотреблять такими вещами (хотя иногда можно, когда хочется звучать почеловечнее, показать что вы слушаете, как на самом деле говорят "обычные люди"), всё это довольно таки серая зона, которую надо научиться чувствовать и использовать аккуратно и в меру.

Но чтобы уметь нащупывать этот момент и использовать его во благо, врага надо знать в лицо, так сказать "практиковать митридатизм".

Предлагаю к ознакомлению бессмертную классику прямиком из 1991 "Как отказаться от обтекаемых выражений" (🇺🇸)

Для упрощения жизни себе и другим, постарайтесь автоматизировать это не только в голове (да, это сложно, слишком много переменных нужно держать в уме) но и современными тулзами. В этом вам поможет или наш старый добрый правильно настроенный друг Vale или отдельно живущий write-good. И тот и другой можно настроить на проверку weasel words (и в качестве приятного бонуса можно даже включить подсказки E-Prime)

#language #en #testthedocs

Хороший пост-пища-для-размышлений на idratherbewriting.

>Почему технических писателей часто считают столь неважной частью компании?

И еще бонусный пост из комментариев (их тоже почитайте, там хорошо). О грамотном наборе компетенций для современного писателя и о том, почему "технический писатель" не самое удачное название профессии. Он предлагает "complexity translator".

Понравилось оттуда:

>Technical writing could be compared to documenting all the components of a car’s engine. You’ll write down their names and how some parts are connected to other parts. That does not mean you’re qualified to get under the hood of the car and assemble an engine with those parts. But you could work with a technical person to translate their instructions into useable directions.

P.S:
Постить статьи с idratherbewriting слегка моветон, но как показывает практика, далеко не все смотрят по сторонам и вообще что-то читают по теме. Следовательно (в)опрос, вы как, сами почитаете или вам сюда иногда набрасывать интересного?

#en #article #career