Сайт с конспектами документации разработчика: “TL;DR for developer documentation”.
https://devhints.io/
https://devhints.io/
Devhints.io cheatsheets
https://assets.devhints.io/previews/index.jpg
A ridiculous collection of web development cheatsheets
Изучаю Докер по урокам на сайте play-with-docker.com. Сайт очень классно сделан: слева — текст инструкций, справа — интерактивная консоль. Когда кликаешь на блоке кода в инструкции, он выполняется в консоли.
https://i.imgur.com/7MSteaw.png
https://i.imgur.com/7MSteaw.png
Сайт сделан на Jekyll, исходники — в Markdown. Джекил собирает статические страницы и в каждую добавляет код JavaScript, который загружает динамическую консоль.
Консолей может быть несколько. Соответствие консоли и блока задается прямо в исходнике. После тройного бэктика — номер консоли: https://i.imgur.com/6g0xwUq.png
Консолей может быть несколько. Соответствие консоли и блока задается прямо в исходнике. После тройного бэктика — номер консоли: https://i.imgur.com/6g0xwUq.png
Самое классное, что сам этот сайт собирается в докере одной командой
Не нужно ставить Jekyll и зависимости, разбираться в командах для сборки, вручную искать index.html. Всё просто работает.
Сам сайт: https://training.play-with-docker.com
Исходники: https://github.com/play-with-docker/play-with-docker.github.io
docker-compose up. Результат сразу виден по адресу http://localhost:4000/.Не нужно ставить Jekyll и зависимости, разбираться в командах для сборки, вручную искать index.html. Всё просто работает.
Сам сайт: https://training.play-with-docker.com
Исходники: https://github.com/play-with-docker/play-with-docker.github.io
Play-With-Docker
Play with Docker Classroom
Learn docker through online trainings in training.play-with-docker.com
Forwarded from Kostya Gorsky’s Channel
В феврале 2013 продакт-менеджер из Гугла Тристан Харрис разослал своим коллегам любопытную презентацию. В презентации говорилось, что продукты таких компаний как Гугл и Фейсбук довольно нагло захватывают внимание людей, паразитируя на особенностях восприятия. И что компании пора бы задуматься об ответственности за то, что миллиарды людей всё больше времени проводят, залипая в устройства.
Презентация вызывала серьёзные дискуссии внутри Гугла, хотя поначалу никак не повлияла на то, что компания делала. У Тристана появились последователи, на презентацию время от времени ссылались. Мне рассказывали про это всё бывшие гуглеры, с которыми сейчас мы вместе работаем в Интеркоме.
Руководство компании поступило мудро, Тристана официально назначили дизайн-этиком. Правда, ничего сделать в этой роли у него не получилось, и спустя пару лет он уволился.
Вне компании наш герой основал движение Centre for Human Technology (humanetech.com) и выступил с докладом на TED —ted.com/talks/tristan_harris_the_manipulative_tricks_tech_companies_use_to_capture_your_attention
А вспомнил я про всю эту историю вот почему.
Во-первых, на конференции Google I/O 8 мая, 5 лет спустя после того, как Тристан расшарил свою презентацию, целая большая часть была посвящена Digital Wellbeing (wellbeing.google) — новой инициативе Гугла, которая посвящена тому, чтобы телефон пожирал меньше нашего внимания. В частности, в новой версии Андроида:
- можно будет видеть, сколько раз в день ты брал телефон и сколько минут провёл в каком приложении (на айфоне для такого же есть приложение Moment);
- поставить себе напоминание сделать перерыв, если ты залип в телефон надолго;
- выключить все нотификации, положив телефон экраном вниз.
Это же офигенно!
А во-вторых, та самая презентация Тристана появилась в открытом доступе: https://www.scribd.com/document/378841682/A-Call-to-Minimize-Distraction-Respect-Users-Attention-by-Tristan-Harris
Мне кажется, её стоит посмотреть, если вы ещё не видели. Это крутой пример очень простой и убедительной коммуникации. Чёткая структура, смешные примеры, одна мысль на слайд. Многие спрашивают, как можно повлиять на мнение окружающих и стать лидером какой-то инициативы. Вот так можно, например.
А ещё мне очень импонирует посыл. Уже писал, например, про свою информационную диету (t.me/desprod/270) или про то, почему не хотел бы работать в Фейсбуке (t.me/desprod/6).
Презентация вызывала серьёзные дискуссии внутри Гугла, хотя поначалу никак не повлияла на то, что компания делала. У Тристана появились последователи, на презентацию время от времени ссылались. Мне рассказывали про это всё бывшие гуглеры, с которыми сейчас мы вместе работаем в Интеркоме.
Руководство компании поступило мудро, Тристана официально назначили дизайн-этиком. Правда, ничего сделать в этой роли у него не получилось, и спустя пару лет он уволился.
Вне компании наш герой основал движение Centre for Human Technology (humanetech.com) и выступил с докладом на TED —ted.com/talks/tristan_harris_the_manipulative_tricks_tech_companies_use_to_capture_your_attention
А вспомнил я про всю эту историю вот почему.
Во-первых, на конференции Google I/O 8 мая, 5 лет спустя после того, как Тристан расшарил свою презентацию, целая большая часть была посвящена Digital Wellbeing (wellbeing.google) — новой инициативе Гугла, которая посвящена тому, чтобы телефон пожирал меньше нашего внимания. В частности, в новой версии Андроида:
- можно будет видеть, сколько раз в день ты брал телефон и сколько минут провёл в каком приложении (на айфоне для такого же есть приложение Moment);
- поставить себе напоминание сделать перерыв, если ты залип в телефон надолго;
- выключить все нотификации, положив телефон экраном вниз.
Это же офигенно!
А во-вторых, та самая презентация Тристана появилась в открытом доступе: https://www.scribd.com/document/378841682/A-Call-to-Minimize-Distraction-Respect-Users-Attention-by-Tristan-Harris
Мне кажется, её стоит посмотреть, если вы ещё не видели. Это крутой пример очень простой и убедительной коммуникации. Чёткая структура, смешные примеры, одна мысль на слайд. Многие спрашивают, как можно повлиять на мнение окружающих и стать лидером какой-то инициативы. Вот так можно, например.
А ещё мне очень импонирует посыл. Уже писал, например, про свою информационную диету (t.me/desprod/270) или про то, почему не хотел бы работать в Фейсбуке (t.me/desprod/6).
Вчера по приглашению Семёна Факторовича прочитал лекцию на его курсе по разработке технической документации. Поделился мыслями о парадигме DocOps. Во многом это адаптация DevOps к задачам и процессам документирования: общие с разработкой инструменты и процессы, в которых писатели отчасти становятся разработчиками, админами и дизайнерами; а те, в свою очередь, становятся писателями.
Вот запись лекции: https://www.youtube.com/watch?v=xo6pAFZ135I
А вот курс Тома Джонсона по документированию API: http://idratherbewriting.com/learnapidoc/index.html. Основная часть курса посвящена REST API — интерфейсам для взаимодействия между приложениями по сети. Есть раздел и про «библиотечные» (native library) интерфейсы — внутри приложений и на уровне программного кода.
Начал разбираться с этим курсом, на следующей неделе опубликую перевод первого фрагмента.
Предлагаю вместе проходить курс и делиться опытом. Если хотите научиться документировать программные интерфейсы — присоединяйтесь. Напишите мне (@Nick_Volynkin). Начнём сразу, как опубликую перевод.
Вот запись лекции: https://www.youtube.com/watch?v=xo6pAFZ135I
А вот курс Тома Джонсона по документированию API: http://idratherbewriting.com/learnapidoc/index.html. Основная часть курса посвящена REST API — интерфейсам для взаимодействия между приложениями по сети. Есть раздел и про «библиотечные» (native library) интерфейсы — внутри приложений и на уровне программного кода.
Начал разбираться с этим курсом, на следующей неделе опубликую перевод первого фрагмента.
Предлагаю вместе проходить курс и делиться опытом. Если хотите научиться документировать программные интерфейсы — присоединяйтесь. Напишите мне (@Nick_Volynkin). Начнём сразу, как опубликую перевод.
YouTube
Курс «Техническая документация в IT-проектах», лекция 8
http://documentat.io/courses/open-course
Открытый курс о технической документации в IT-проектах, читаемый в Новосибирском государственном университете.
Лекция 8, о методологии docs as code.
Открытый курс о технической документации в IT-проектах, читаемый в Новосибирском государственном университете.
Лекция 8, о методологии docs as code.
Конечно, мы любим документацию!
Отличная подборка текстовых форматов для диаграмм и схем. Спасибо автору! В целом канал @lovely_it_hell полон годных мыслей, очень рекомендую.
Отличная подборка текстовых форматов для диаграмм и схем. Спасибо автору! В целом канал @lovely_it_hell полон годных мыслей, очень рекомендую.
Forwarded from Уютный IT адочек
Я знаю, некоторые из вас любят документацию и схемки настолько же сильно, как я.
https://modeling-languages.com/text-uml-tools-complete-list/
Вот вам интересная ссылка с подборкой инструментов по визуализации UML
https://modeling-languages.com/text-uml-tools-complete-list/
Вот вам интересная ссылка с подборкой инструментов по визуализации UML
Modeling Languages
From Text to Models: A Comprehensive Guide to Textual Modeling and Diagrams as Code Tools in 2024
Sometimes the easiest way to draw a model is to "write" it down. These tools will render nicely looking UML diagrams from a few lines of text.
Конференция CodeFest опубликовала записи выступлений: https://2018.codefest.ru/program/.
Есть интересный доклад про использование чатбота-ассистента для доступа к базе знаний. https://2018.codefest.ru/lecture/1370/
Есть интересный доклад про использование чатбота-ассистента для доступа к базе знаний. https://2018.codefest.ru/lecture/1370/
2018.codefest.ru
Программа CodeFest 2018
Конференция разработчиков, посвященная вопросам разработки, управления проектами и тестирования.
txti.es
txti.es — cайт для публикации одностраничных документов c акцентом на скорости и малом размере страниц. Примерно как telegra.ph, но не совсем такой же.
Текст в txti.es пишется в разметке Markdown. Когда вы впервые сохраняете документ, сервис даёт ему случайный адрес, но можно выбрать свой. Чтобы потом редактировать документ, нужен пароль — “edit code”. Его сервис тоже выдаёт, и тоже можно задать свой.
Тест на поддержку Markdown
Проверил, что у txti.es с поддержкой Markdown. Вот мой тестовый документ: txti.es/markup-test, здесь подведу итоги.
Разметка для обычных текстов работает, кроме блока цитаты. Вложенные списки работают — а в telegra.ph я их не нашёл. Картинки и видео можно вставлять только со сторонних сервисов — сами не хостят. По умолчанию картинки на странице не показываются, нужно нажать кнопку. Всё для быстрой загрузки!
С оформлением кода большие проблемы: в блоках кода строки слипаются, кавычки заменяются на
Тест на размер и скорость
Размер страницы действительно впечатляет. Вот график загрузки страниц с одинаковым содержимым. Дал ссылки, чтобы вы могли проверить сами.
txti.es: 2 запроса, 2,6 килобайта.
txti.es — cайт для публикации одностраничных документов c акцентом на скорости и малом размере страниц. Примерно как telegra.ph, но не совсем такой же.
Текст в txti.es пишется в разметке Markdown. Когда вы впервые сохраняете документ, сервис даёт ему случайный адрес, но можно выбрать свой. Чтобы потом редактировать документ, нужен пароль — “edit code”. Его сервис тоже выдаёт, и тоже можно задать свой.
Тест на поддержку Markdown
Проверил, что у txti.es с поддержкой Markdown. Вот мой тестовый документ: txti.es/markup-test, здесь подведу итоги.
Разметка для обычных текстов работает, кроме блока цитаты. Вложенные списки работают — а в telegra.ph я их не нашёл. Картинки и видео можно вставлять только со сторонних сервисов — сами не хостят. По умолчанию картинки на странице не показываются, нужно нажать кнопку. Всё для быстрой загрузки!
С оформлением кода большие проблемы: в блоках кода строки слипаются, кавычки заменяются на
".Тест на размер и скорость
Размер страницы действительно впечатляет. Вот график загрузки страниц с одинаковым содержимым. Дал ссылки, чтобы вы могли проверить сами.
txti.es: 2 запроса, 2,6 килобайта.
Выводы
— Страницы весят очень мало. Вашим читателям это понравится, если у них медленное или нестабильное соединение.
— Сервис уважает приватность читателей и не собирает никаких данных.
— Хорошо подходит для коротких заметок и конспектов.
— Пока что не подходит для публикации кода. Будем ждать обновлений
#docops_toolkit
— Страницы весят очень мало. Вашим читателям это понравится, если у них медленное или нестабильное соединение.
— Сервис уважает приватность читателей и не собирает никаких данных.
— Хорошо подходит для коротких заметок и конспектов.
— Пока что не подходит для публикации кода. Будем ждать обновлений
#docops_toolkit
Про что написать в следующем посте?
public poll
Обзор отличного примера интерактивной документации (какого — секрет). – 15
👍👍👍👍👍👍👍 65%
@katerina308, @etkee, @factorized, @exebeeche, @annacraneo, @anasta_ste, @DarthVader, @OlgaRevyakina, @SvetlanaNudel, @den317, @woooooowmen, @aselivanava, @slavachernikoff, @arvikon, @space_time_freedom
Как добавлять диаграммы, в том числе UML, в документацию на Sphinx. – 4
👍👍 17%
@yeugene, @Lananovikova, @PavelAlferov, @maxlapshin
Как использовать ссылки в форматах разметки, чтобы они не сломались при переводе. – 2
👍 9%
@Dark_soul_Mike, Екатерина
Память переводов: зачем нужна и как устроена. – 2
👍 9%
@i_tsupko, @vodnicear
👥 23 people voted so far.
public poll
Обзор отличного примера интерактивной документации (какого — секрет). – 15
👍👍👍👍👍👍👍 65%
@katerina308, @etkee, @factorized, @exebeeche, @annacraneo, @anasta_ste, @DarthVader, @OlgaRevyakina, @SvetlanaNudel, @den317, @woooooowmen, @aselivanava, @slavachernikoff, @arvikon, @space_time_freedom
Как добавлять диаграммы, в том числе UML, в документацию на Sphinx. – 4
👍👍 17%
@yeugene, @Lananovikova, @PavelAlferov, @maxlapshin
Как использовать ссылки в форматах разметки, чтобы они не сломались при переводе. – 2
👍 9%
@Dark_soul_Mike, Екатерина
Память переводов: зачем нужна и как устроена. – 2
👍 9%
@i_tsupko, @vodnicear
👥 23 people voted so far.
Резюме современного инженера: репозиторий на Гитхабе с полезными скриптами для администрирования Debian, а в заголовке — ссылка на CV.
У репозитория 124 звезды, это довольно неплохо. Мой рекорд - шесть.
В резюме автор сразу пишет по делу: что умеет, что предлагает, какие принципы исповедует. Мне нравится, это вызывает интерес и доверие.
https://github.com/szepeviktor/debian-server-tools
У репозитория 124 звезды, это довольно неплохо. Мой рекорд - шесть.
В резюме автор сразу пишет по делу: что умеет, что предлагает, какие принципы исповедует. Мне нравится, это вызывает интерес и доверие.
https://github.com/szepeviktor/debian-server-tools
GitHub
GitHub - szepeviktor/debian-server-tools: Tools and living docs 🧬 for Debian-based servers and Web Applications
Tools and living docs 🧬 for Debian-based servers and Web Applications - szepeviktor/debian-server-tools
Производите или документируете CLI-утилиту, в которой куча команд с параметрами? Подумайте про вот такой конструктор команд: http://ru.clihelper.com/. Думаю, что он будет полезен и пользователям, и вам самим:
— Поможет пользователю увидеть общую картину и сориентироваться в возможностях утилиты.
— Поможет собрать сложные команды, которые сразу будут работать правильно. Это снижает время до первого успешного использования, и этим улучшает конверсию из тех кто попробовал в тех, кто стал постоянным пользователем.
— Поможет разработчикам поддерживать консистентный синтаксис команд и понятную структуру. Они будут яснее видеть, когда структура теряет логику и порядок.
Мы в Plesk.com ещё не пробовали такое, но наверняка попробуем. О результатах расскажу.
— Поможет пользователю увидеть общую картину и сориентироваться в возможностях утилиты.
— Поможет собрать сложные команды, которые сразу будут работать правильно. Это снижает время до первого успешного использования, и этим улучшает конверсию из тех кто попробовал в тех, кто стал постоянным пользователем.
— Поможет разработчикам поддерживать консистентный синтаксис команд и понятную структуру. Они будут яснее видеть, когда структура теряет логику и порядок.
Мы в Plesk.com ещё не пробовали такое, но наверняка попробуем. О результатах расскажу.
Clihelper
cli helper. Помощники
cli helper. Any docs, documents, manual, tutorial about unix and linux command. Option reminder for unix command. cli helper.
Ещё один интересный способ облегчить жизнь пользователя и помочь ему освоить интерфейс командной строки:
Forwarded from Записки админа
👱🏻 Natural Language для Linux.
Чего только не делают люди. Вот вам, например, попытка создания преобразователя, который бы трансформировал обычную (английскую в данном случае) письменную речь, в bash команды для управления оперционной системой (речь о Linux, конечно же).
С технарями всё и так понятно - знаем команды, знаем где посмотреть описание, знаем и умеем всем этим пользоваться. Данный же проект, ставит перед собой задачу упростить работу пользователя с командной строкой. В идеале, ему не нужно будет запоминать команды и их синтаксис, достаточно будет просто написать, например "Найди все файлы, которые были модифицированы в последние два дня" и система выполнит соответствующую команду find с нужными параметрами.
Нужен ли он? С точки зрения админа - вряд ли, но вот с точки зрения пользователя - это как минимум выглядит интересно.
Документ на 12 страницах с описанием, ссылками и исследованием доступен здесь:
https://arxiv.org/abs/1802.08979
#linux #bash
Чего только не делают люди. Вот вам, например, попытка создания преобразователя, который бы трансформировал обычную (английскую в данном случае) письменную речь, в bash команды для управления оперционной системой (речь о Linux, конечно же).
С технарями всё и так понятно - знаем команды, знаем где посмотреть описание, знаем и умеем всем этим пользоваться. Данный же проект, ставит перед собой задачу упростить работу пользователя с командной строкой. В идеале, ему не нужно будет запоминать команды и их синтаксис, достаточно будет просто написать, например "Найди все файлы, которые были модифицированы в последние два дня" и система выполнит соответствующую команду find с нужными параметрами.
Нужен ли он? С точки зрения админа - вряд ли, но вот с точки зрения пользователя - это как минимум выглядит интересно.
Документ на 12 страницах с описанием, ссылками и исследованием доступен здесь:
https://arxiv.org/abs/1802.08979
#linux #bash
Игорь Цупко рассказывает про системный и целостный подход к внутренней документации: про инструменты, процессы и цели. Рекомендую.