Немножко про организацию документации.

https://medium.com/@brooke.wayne/how-to-organize-your-docs-bd797c616b48

Статья описывает базовые вещи, но интересный тейкэвэй оттуда это термин Undernets:

>Undernets are the “non-formal and unintentionally walled off bits of knowledge that [folx] document in private”, also known as “rogue docs or sheets [others] create for themselves. These are often incorrect, out of date, or not shared with the entire team.”

#knowledgemanagement #resource #en

Для быстрых (как публичных, так и приватных) заметок поверх любой веб-странички (а также PDF и EPUB) пытаюсь пользоваться https://web.hypothes.is

Если вы плотно работаете над текстовкой какого-либо сайта/книги то вот это то, что нужно

#tool #en

Наткнулся тут на бложик техрайтера из Google, он пишет документацию для Chrome DevTools.

Очень понравилась оттуда статья про то, что может и не все бест практисы одинаково полезны (а может и полезны!) и применимы и размышления на счёт того, что со всей этой информацией нам делать и как измерять полезность конкретно взятой доки (солюшен очень прост и я с ним согласен)

https://kayce.basqu.es/blog/best-practices

Остальное тоже почитайте!

#resource #en #article

Анимированные презентации терминала. Можно экспортировать в SVG, GIF, или HTML+CSS

https://neatsoftware.github.io/term-sheets/

Вдруг пригодится.

#tool #visual #screenshot

Что бы вы выбрали?
anonymous poll

Go to File, and then select Save. – 49
👍👍👍👍👍👍👍 67%

Select Save from the File menu. – 24
👍👍👍 33%

👥 73 people voted so far.

⚡️⚡️⚡️

Свершилось! Один из самых гибких линтеров (Vale) вот-вот станет работать с sandboxed приложениями (читай Google Docs, Microsoft Word, Chrome)

https://medium.com/@jdkato/vale-comes-to-the-desktop-b813b24b66ba

#tool #testthedocs #en

На горизонте никаких интересных статеек, да и уже пятница, чо напрягаться.

Пусть и с запозданием, но вот хорошее пятничное чтиво от Increment про open-source, коммьюнити и иже с ними.

https://increment.com/open-source/

Вообще Increment отличное издание, советую подписаться и почитывать чем живут современные команды (RSS для понимающих)

#resource #article #en

Давненько в закладках лежит хороший разбор плюшек, которые предоставляют Docz, Storybook и Styleguidist для интерактивной документации UI-компонентов (и API'шек)

Кроме того, в статье хорошим и понятным языком рассказывают, что такое MDX

https://css-tricks.com/front-end-documentation-style-guides-and-the-rise-of-mdx/

#uiux #tool #en

Обновился до 4-й версии Markdown-редактор Inkdrop. Честно говоря, я уже совсем перестал обращать внимание на "специализированные" Markdown-редакторы, т.к ничем они друг от друга не отличаются и ужасно ограничены в наборе фукций. Но Inkdrop это исключение, ведь там есть плагины и даже полезные! До VSCode еще как до луны, но потенциал имеется, пробуйте.

#ide #en #markdown

Статья Федеральной торговой комиссии (ребята, что в США защищают правами потребителей и занимаются антимонопольной деятельностью) — "Как Технические Писатели могут способствовать безопасности программного обеспечения"

https://www.ftc.gov/about-ftc/bureaus-offices/bureau-consumer-protection/office-technology-research-investigation/guiding-to-safety-how-technical-documentation-writers-can-encourage-software-security

#career #en #article

А почитайте (не сейчас, конечно, вечер пятницы, алло. В Pocket там закиньте.) как-нибудь про наречия, хороший пост на Quora:

https://www.quora.com/Why-are-adverbs-considered-evil-I-keep-hearing-eliminate-adverbs-as-a-piece-of-writing-advice

#language #en #resource

В Google Docs наконец-то изобрели diff! <— это ссылка

#tool

Не могу не поделиться с вами очень хорошей новостью, в бету вышла Windows Subsystem for Linux 2.

К техрайтингу слабо относится, но я, напрмиер, гоняю там pandoc без всяких извращений.

https://devblogs.microsoft.com/commandline/wsl-2-is-now-available-in-windows-insiders/

P.S

Еще Microsoft активно педалит НОРМАЛЬНЫЙ терминал для всего этого дела вот тут (где брать готовые сборки я забыл, если вдруг соберете или найдете свеженькое - делитесь)

#tool

В Apple выкатили новую документацию и она великолепна!
"Параллаксный" скроллинг, всё аккуратно, аскетично и очень информативно, а главное — вконце есть раздел "Check Your Understanding" с вопросами по самой доке, берите на заметку:

https://developer.apple.com/tutorials/swiftui/creating-and-combining-views

Если вам лениво клепать аккуратные описания проекта, проставлять ссылочки и вот это вот всё, то вот вам генератор красивых README.md. Задаёт вопросы и за 10 секунд выплёвывает свёрстанный файлик 💫

У бота отклеилась ссылочка

#tool

Очень люблю Markdown и тут вот прилетел интересный вариант его применения в качестве замены Speech Synthesis Markup Language (SSML), на основе которого строятся ответы ботов типа Alexы и Google Assistant. https://voicebot.ai/2019/06/20/speech-markdown-is-the-simpler-way-to-format-text-to-speech-content-over-ssml/

#markdown

Почитайте интересный тред Продакт Менеджера docs.microsoft.com (одного из самых массивных сайтов документации, к слову)

https://twitter.com/DennisCode/status/1144108469617774592

TL;DR

Takeaways из треда:

1. Documentation is not easy.
2. Automation is key at scale.
3. Documentation is a partnership.
4. Users are part of the success equation.
5. Quantitative data without qualitative insights is not going to help you make good decisions.
6. Shared understanding can be achieved when things are written down.
7. Being attached to ideas is useless.
8. Avoid the "too many cooks" problem.
9. You will be wrong more than you will be right

#resource #article #en #career

Хороший, годный цикл постов про дружбу Markdown + ConTeXt (типографский брат LaTeX) и Pandoc

Зачем?

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

1. https://dave.autonoma.ca/blog/2019/05/22/typesetting-markdown-part-1/
2. https://dave.autonoma.ca/blog/2019/05/29/typesetting-markdown-part-2/
3. https://dave.autonoma.ca/blog/2019/06/16/typesetting-markdown-part-3/
4. https://dave.autonoma.ca/blog/2019/06/23/typesetting-markdown-part-4/

#visual #uiux #en #markdown

Недавно пришлось иметь дела с ZenDesk и писать в нём буквы (а точнее переносить всё из Markdown в туда) и не могу сказать, что это был приятный экспириенс. Но нашлась вот такая тулза, которой можно скормить логин инфу и API токенчик и пушить это всё прям вот как вы себе и представляете.
Делюсь — https://github.com/mbuttler/docs-tools

Будем попробовать, а пока открыл комменты к посту и если у кого-то вдруг есть варианты получше (чтобы без sigh Ruby всё было, например) — дайте знать!

P.S Любители Руби, не обижайтесь!