Конспект про документацию как код: как это устроено, в чём преимущества. http://hackwrite.com/posts/docs-as-code/
hack.write()
Docs as Code
Practices
Docs are written in plain text formats such as Markdown or reStructured Text.
Docs are stored as flat files, not database entries.
Docs are authored in a code editor of the writer's choice,
Docs are written in plain text formats such as Markdown or reStructured Text.
Docs are stored as flat files, not database entries.
Docs are authored in a code editor of the writer's choice,
Не совсем про код, но сделано очень хорошо. Было бы удобно иметь стайлгайды в такой форме.
Классификатор с сотней инструментов для редактирования и публикации документации. CMS, генераторы статических сайтов, редакторы XML, инструменты переводчика, вики-системы и всё остальное.
Выбор по операционной системе, платно-бесплатно, форматам входных данных и локализации, форматам для публикации, стандартам описания API.
https://doctoolhub.com
Выбор по операционной системе, платно-бесплатно, форматам входных данных и локализации, форматам для публикации, стандартам описания API.
https://doctoolhub.com
Сайт с конспектами документации разработчика: “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