SEO для документации.
Read the Docs опубликовали руководство по search engine optimization для документации. В отличие от руководств по SEO «вообще», в этом есть конкретные примеры разметки reStructuredText. Например, я ни разу не заполнял метаданные, а теперь буду:
Читать тут: https://docs.readthedocs.io/en/latest/guides/technical-docs-seo-guide.html
Read the Docs опубликовали руководство по search engine optimization для документации. В отличие от руководств по SEO «вообще», в этом есть конкретные примеры разметки reStructuredText. Например, я ни разу не заполнял метаданные, а теперь буду:
meta::
:description lang=en:
Adding additional CSS or JavaScript files
to your Sphinx documentation can let
you customize the look and feel of your
docs or add additional functionality.
Читать тут: https://docs.readthedocs.io/en/latest/guides/technical-docs-seo-guide.html
pandoc умеет конвертировать DOCX в reST, Markdown или AsciiDoc вместе с изображениями:
Изображения будут в директории
pandoc -f docx --extract-media images -t rst -o document.rst document.docx
pandoc -f docx --extract-media images -t markdown -o document.md document.docx
pandoc -f docx --extract-media images -t asciidoc -o document.adoc document.docx
Изображения будут в директории
images.
В любой разметке сразу будут правильные ссылки на них.Аттракцион «почувствуй себя нубом».
Читаю в доке Jekyll про то, как использовать шаблоны Liquid прямо в исходниках страниц. Это помогает раскладывать структурированные данные в HTML и переиспользовать готовые блоки с помощью
В сотый раз грущу, что такое есть в Jekyll, Hugo, вообще где угодно, кроме Sphinx.
В отчаянии гуглю и первой ссылкой нахожу статью 2016 года, в которой Eric Holscher в десять строк кода на Python добавляет эту фичу в Sphinx.
Эрик, ну как я теперь с этим буду жить?
Читаю в доке Jekyll про то, как использовать шаблоны Liquid прямо в исходниках страниц. Это помогает раскладывать структурированные данные в HTML и переиспользовать готовые блоки с помощью
include
. И это очень удобно.В сотый раз грущу, что такое есть в Jekyll, Hugo, вообще где угодно, кроме Sphinx.
В отчаянии гуглю и первой ссылкой нахожу статью 2016 года, в которой Eric Holscher в десять строк кода на Python добавляет эту фичу в Sphinx.
Эрик, ну как я теперь с этим буду жить?
Докеризованный Pandoc и куча фильтров Pandoc для разных задач: https://github.com/pandocker
JetBrains давно используют собственный инструмент для документации, а теперь хотят его опубликовать.
Если вы пишете документацию, заполните опрос. Так вы поможете JB сделать хороший и полезный инструмент. Опрос короткий, у меня он занял вдумчивых 15 минут.
Если вы пишете документацию, заполните опрос. Так вы поможете JB сделать хороший и полезный инструмент. Опрос короткий, у меня он занял вдумчивых 15 минут.
Трансляция Write the Docs Prague.
Сегодня и завтра в Праге проходит конференция Write the Docs.
Программа на сегодня, 16 сентября:
— The Super Effective Writing Process of Grammy-winning Artists
— How to write the perfect error message
— How to launch your startup with good docs
— Surprise! You're a designer now
— Documenting known unknowns
— Write the API docs before the API exists
— Disagree with “I Agree”. Enforcing better data privacy through the language of documentation
— Inclusive environments are just better: science says so
Есть бесплатная трансляция: https://www.writethedocs.org/conf/prague/2019/livestream/.
Сегодня и завтра в Праге проходит конференция Write the Docs.
Программа на сегодня, 16 сентября:
— The Super Effective Writing Process of Grammy-winning Artists
— How to write the perfect error message
— How to launch your startup with good docs
— Surprise! You're a designer now
— Documenting known unknowns
— Write the API docs before the API exists
— Disagree with “I Agree”. Enforcing better data privacy through the language of documentation
— Inclusive environments are just better: science says so
Есть бесплатная трансляция: https://www.writethedocs.org/conf/prague/2019/livestream/.
Documentation as bash history!
Попалась интересная статья про Infrastructure as code (IaC). Автор противопоставляет правильное IaC неправильному:
«Предположим, приходите вы на новый проект, а вам говорят: "у нас Infrastructure as Code". В реальности оказывается, Infrastructure as bash history или, например, Documentation as bash history.»
Ссылку увидел в @chiki_briki_it через @count0_digest — спасибо!
Попалась интересная статья про Infrastructure as code (IaC). Автор противопоставляет правильное IaC неправильному:
«Предположим, приходите вы на новый проект, а вам говорят: "у нас Infrastructure as Code". В реальности оказывается, Infrastructure as bash history или, например, Documentation as bash history.»
Ссылку увидел в @chiki_briki_it через @count0_digest — спасибо!
DocOps
Documentation as bash history! Попалась интересная статья про Infrastructure as code (IaC). Автор противопоставляет правильное IaC неправильному: «Предположим, приходите вы на новый проект, а вам говорят: "у нас Infrastructure as Code". В реальности оказывается…
Признайтесь, у кого бывает documentation as bash history?
Anonymous Poll
32%
У нас только так и бывает
51%
Случается
17%
Нет, что вы, у нас всё в коде
Сообщество Write the Docs на TeamLeadConf SPb.
Впереди TeamLeadConf SPb! Пока что я отдыхаю от конференций (т.е. просто работаю), а мои коллеги по сообществу Write the Docs придут. Приходите к ним на стенд с вашими вопросами про документацию.
Если хотите что-то обсудить заранее, приходите с вопросами в чат @docsascode.
Стенд будет выглядеть вот так:
Впереди TeamLeadConf SPb! Пока что я отдыхаю от конференций (т.е. просто работаю), а мои коллеги по сообществу Write the Docs придут. Приходите к ним на стенд с вашими вопросами про документацию.
Если хотите что-то обсудить заранее, приходите с вопросами в чат @docsascode.
Стенд будет выглядеть вот так:
Forwarded from TeamLead Сonf++
Есть вопросы по технической документации? Не знаете, какой выбрать инструмент или на кого возложить ответственность за документирование? Спросите на стенде DocOps.
Толковый пост о технических писателях: кто такие, что умеют, в чём польза.
https://t.me/bor_64/94
https://t.me/bor_64/94
Telegram
Bor64
👨🏿💻 Технический писатель 👨🏿💻
Кто знает, что за профессия такая "Технический писатель"? Вообще кто-нибудь слышал о ней?
🤔 Кто это.
Как гласит Wikipedia:
Технический писатель — специалист, занимающийся документированием в рамках решения технических задач…
Кто знает, что за профессия такая "Технический писатель"? Вообще кто-нибудь слышал о ней?
🤔 Кто это.
Как гласит Wikipedia:
Технический писатель — специалист, занимающийся документированием в рамках решения технических задач…
Налоговая служба Украины написала документацию к своему электронному кабинету на Sphinx/reST. В сайте узнаётся тема Read the Docs, можно скачать PDF и EPUB. Я считаю, для госоргана это очень круто и современно.
https://cabinet.tax.gov.ua/help/intro.html
Не хватает только кода на гитхабе и простого канала обратной связи. Нашёл баг, ищу как зарепортить. :)
https://cabinet.tax.gov.ua/help/intro.html
Не хватает только кода на гитхабе и простого канала обратной связи. Нашёл баг, ищу как зарепортить. :)
Forwarded from Технологический Болт Генона
Доклады с Write the Docs meetup - Stockholm
https://www.youtube.com/playlist?list=PL26ma051UtkOo1HZ5lcMTKbJ5AQ31hkWr
https://www.youtube.com/playlist?list=PL26ma051UtkOo1HZ5lcMTKbJ5AQ31hkWr
Какие самые крутые changelog'и вы видели? А какие вы внимательно читаете перед каждым обновлением? От каких больше всего пользы?
Расскажите в @docsascode, а?
Расскажите в @docsascode, а?
R Markdown: The Definitive Guide
Всего неделю назад вышла новая книга про R Markdown. Казалось бы, зачем миру ещё одна реализация Markdown?
Во-первых, в R Markdown всё очень хорошо с выходными форматами: HTML, PDF, DOCX, четыре разных формата слайдов. Приятно иметь это всё сразу и не собирать цепочку из нескольких инструментов.
Во-вторых, есть выполняемые блоки кода, которые рисуют диаграммы и любой другой контент в документе. Код можно писать на R, Python, Julia, C++, С, SQL, Fortran и других языках. Я пока не успел попробовать, но выглядит это гораздо мощнее, чем обычные языки шаблонизации вроде Jinja и Liquid. Конечно, можно к любому SSG написать своё расширение, которое будет делать что угодно при сборке документа, но тут-то не нужны расширения.
Я думаю, это очень крутая фича. Она открывает путь к автодокументированию в принципе любых данных, которые вы можете собрать программно.
В-третьих, в R Markdown есть режим R Notebook — когда блоки кода на R выполняются интерактивно. Вроде бы можно переиспользовать один документ с разными источниками данных. Если вы знакомы с Jupyter Notebook — это примерно оно же, только на R.
А ещё в комплекте с R Markdown есть сервис Bookdown — инструмент для написания и публикации чего угодно на R Markdown. На нём уже написана куча книг по языку R. Конечно, на нём же сделана книга-документация по R Markodwn и ещё одна книга про сам сервис Bookdown.
В общем, это не просто 101й парсер, а целая развитая экосистема. Стоит попробовать, особенно если ваша работа связана с обработкой данных.
На скриншоте — документ R Markdown и собираемая из него интерактивная страница с визуализацией данных (источник).
Всего неделю назад вышла новая книга про R Markdown. Казалось бы, зачем миру ещё одна реализация Markdown?
Во-первых, в R Markdown всё очень хорошо с выходными форматами: HTML, PDF, DOCX, четыре разных формата слайдов. Приятно иметь это всё сразу и не собирать цепочку из нескольких инструментов.
Во-вторых, есть выполняемые блоки кода, которые рисуют диаграммы и любой другой контент в документе. Код можно писать на R, Python, Julia, C++, С, SQL, Fortran и других языках. Я пока не успел попробовать, но выглядит это гораздо мощнее, чем обычные языки шаблонизации вроде Jinja и Liquid. Конечно, можно к любому SSG написать своё расширение, которое будет делать что угодно при сборке документа, но тут-то не нужны расширения.
Я думаю, это очень крутая фича. Она открывает путь к автодокументированию в принципе любых данных, которые вы можете собрать программно.
В-третьих, в R Markdown есть режим R Notebook — когда блоки кода на R выполняются интерактивно. Вроде бы можно переиспользовать один документ с разными источниками данных. Если вы знакомы с Jupyter Notebook — это примерно оно же, только на R.
А ещё в комплекте с R Markdown есть сервис Bookdown — инструмент для написания и публикации чего угодно на R Markdown. На нём уже написана куча книг по языку R. Конечно, на нём же сделана книга-документация по R Markodwn и ещё одна книга про сам сервис Bookdown.
В общем, это не просто 101й парсер, а целая развитая экосистема. Стоит попробовать, особенно если ваша работа связана с обработкой данных.
На скриншоте — документ R Markdown и собираемая из него интерактивная страница с визуализацией данных (источник).
R Markdown настолько хорош, что попал под блокировку :)
https://t.me/zatelecom/11815
https://t.me/zatelecom/11815
Telegram
ЗаТелеком
Зае... мечательно. На этот раз под коллатеральные блокировки попал ресурс R Markdown. Это такая система публикации научных отчетов на языке R. Я заметил потому что обновиться не смог.
Что, сука, характерно, IP-адрес 167.99.137.12 попадал в реестр ПЯТЬ РАЗ.…
Что, сука, характерно, IP-адрес 167.99.137.12 попадал в реестр ПЯТЬ РАЗ.…