Ставьте важное вперёд.
Пишет Александр Парень (@SashP84):
Почитываю блоги про авицию. Один из действующих лётчиков разбирает и публикует всякие материалы по тем или иным моментам. Так вот, все помнят, что были две катастрофы Boeing 737MAX, там выяснилось, что была недоработка ПО, но в данном материале пилот отмечает, что оказывается на заметку "Note" в инструкциях никто не обращает внимания.
https://denokan.livejournal.com/207143.html
По ссылке обсуждают инструкцию к самолёту. В ней текст с такой структурой:
Сделайте А
Note: но если выполнено условие X, сначала сделайте Б, иначе случится что-нибудь плохое. (Сделать Б после А технически невозможно).
В критической ситуации человек читает и выполняет первую инструкцию, а потом уже находит вторую. Или не находит. Иногда это приводит к катастрофе.
Вывод автора блога: блок нужно называть Warning, а не Note, и ставить перед остальным текстом. Так у читателя будет меньше шансов пропустить этот блок и больше шансов спасти самолёт.
Не все пишут инструкции к самолётам, но правило-то работает везде. Важное — вперёд.
Пишет Александр Парень (@SashP84):
Почитываю блоги про авицию. Один из действующих лётчиков разбирает и публикует всякие материалы по тем или иным моментам. Так вот, все помнят, что были две катастрофы Boeing 737MAX, там выяснилось, что была недоработка ПО, но в данном материале пилот отмечает, что оказывается на заметку "Note" в инструкциях никто не обращает внимания.
https://denokan.livejournal.com/207143.html
По ссылке обсуждают инструкцию к самолёту. В ней текст с такой структурой:
Сделайте А
Note: но если выполнено условие X, сначала сделайте Б, иначе случится что-нибудь плохое. (Сделать Б после А технически невозможно).
В критической ситуации человек читает и выполняет первую инструкцию, а потом уже находит вторую. Или не находит. Иногда это приводит к катастрофе.
Вывод автора блога: блок нужно называть Warning, а не Note, и ставить перед остальным текстом. Так у читателя будет меньше шансов пропустить этот блок и больше шансов спасти самолёт.
Не все пишут инструкции к самолётам, но правило-то работает везде. Важное — вперёд.
Три отличных расширения для Sphinx: панелька с предупреждением про версию, страница 404 и очень крутой тултип.
Forwarded from Находки в опенсорсе
1. sphinx-version-warning: allows you to add a custom warning banner at the top of your documentation pages to communicate some important about this documentation: https://sphinx-version-warning.readthedocs.io
2. sphinx-notfound-page: is great to create a "Not found" (or 404) page to show when the reader hit a not found page: https://sphinx-notfound-page.readthedocs.io
3. sphinx-hoverxref: adds amazing tooltips on your cross-references that points to another page/section of the documentation including its content on the tooltip: https://sphinx-hoverxref.readthedocs.io
#python
2. sphinx-notfound-page: is great to create a "Not found" (or 404) page to show when the reader hit a not found page: https://sphinx-notfound-page.readthedocs.io
3. sphinx-hoverxref: adds amazing tooltips on your cross-references that points to another page/section of the documentation including its content on the tooltip: https://sphinx-hoverxref.readthedocs.io
#python
Потратил час на то чтобы надёжно добавить CSS в проект на Sphinx. Придумал новую игру «код-конфиг-шаблон»:
— переменная конфига
— вызов функции
— редактирование шаблона бьёт вызов функции.
— переменная конфига
html_css_files бьёт редактирование шаблона layout.html в теме;— вызов функции
app.add_stylesheet бьёт переменную конфига;— редактирование шаблона бьёт вызов функции.
Календарь конференций про документацию и технические коммуникации: https://keycontent.org/Calendar
За ссылку спасибо @SashP84
За ссылку спасибо @SashP84
Introducing Markdown and Pandoc.
В этом месяце вышла новая книга про документацию как код: «Introducing Markdown and Pandoc: Using Markup Language and Document Converter», автор Thomas Mailund.
Если что, Markdown — это самый популярный (хотя не самый мощный) формат разметки, а Pandoc — универсальный конвертер между десятками форматов документов.
Книга начинает с основ Markdown и доходит до использования шаблонов и фильтров (препроцессоров) в Pandoc. Меня особенно порадовала глава про фильтры с примерами кода на Python и panflute. Когда-то я пытался писать фильтры для Pandoc, но не осилил, пришлось обрабатывать уже готовый HTML. Теперь сделаю ещё одну попытку.
Книгу можно купить на сайте издательства. Приятного чтения!
В этом месяце вышла новая книга про документацию как код: «Introducing Markdown and Pandoc: Using Markup Language and Document Converter», автор Thomas Mailund.
Если что, Markdown — это самый популярный (хотя не самый мощный) формат разметки, а Pandoc — универсальный конвертер между десятками форматов документов.
Книга начинает с основ Markdown и доходит до использования шаблонов и фильтров (препроцессоров) в Pandoc. Меня особенно порадовала глава про фильтры с примерами кода на Python и panflute. Когда-то я пытался писать фильтры для Pandoc, но не осилил, пришлось обрабатывать уже готовый HTML. Теперь сделаю ещё одну попытку.
Книгу можно купить на сайте издательства. Приятного чтения!
Митап про документацию в Новосибирске.
Прямо в эту субботу сообщество Konveerum проводит митап про документацию. Место — Новосибирск, Академгородок. Трансляция будет, если вам не слабо начать смотреть её в семь утра по МСК. :)
Сообщество Konveerum — про приборостроение, так что и митап будет с акцентом на ГОСТ, госзаказчиков, и любимые ими форматы DOCX и PDF.
В программе три доклада:
— Алёна Чернышева из Uniscan Research расскажет про то, как компания переехала с MS Word на Atlassian Confluence, но всё равно продолжила использовать Word, и почему всё именно так. Вероятно, доклад будет расширением или продолжением статьи на Хабре.
— Илья Улеско из documentat.io расскажет про переезд c DOCX на reStructuredText. В этом случае получилось переехать полностью, так что теперь уже из исходников в reST генерируется HTML, PDF и DOCX. По словам Ильи, документ в 150 страниц собирается примерно за 20 секунд.
— Дмитрий Перепелин из Моспротекста расскажет про использование DITA XML для разработки конструкторской документации. Дмитрий сообщает, что наиболее востребован формат PDF, но ещё из DITA можно делать (X)HTML, DOCX и EPUB.
Регистрация тут: https://konveerum.ru/
Прямо в эту субботу сообщество Konveerum проводит митап про документацию. Место — Новосибирск, Академгородок. Трансляция будет, если вам не слабо начать смотреть её в семь утра по МСК. :)
Сообщество Konveerum — про приборостроение, так что и митап будет с акцентом на ГОСТ, госзаказчиков, и любимые ими форматы DOCX и PDF.
В программе три доклада:
— Алёна Чернышева из Uniscan Research расскажет про то, как компания переехала с MS Word на Atlassian Confluence, но всё равно продолжила использовать Word, и почему всё именно так. Вероятно, доклад будет расширением или продолжением статьи на Хабре.
— Илья Улеско из documentat.io расскажет про переезд c DOCX на reStructuredText. В этом случае получилось переехать полностью, так что теперь уже из исходников в reST генерируется HTML, PDF и DOCX. По словам Ильи, документ в 150 страниц собирается примерно за 20 секунд.
— Дмитрий Перепелин из Моспротекста расскажет про использование DITA XML для разработки конструкторской документации. Дмитрий сообщает, что наиболее востребован формат PDF, но ещё из DITA можно делать (X)HTML, DOCX и EPUB.
Регистрация тут: https://konveerum.ru/
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::
:denoscription 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
33%
У нас только так и бывает
50%
Случается
17%
Нет, что вы, у нас всё в коде
Сообщество Write the Docs на TeamLeadConf SPb.
Впереди TeamLeadConf SPb! Пока что я отдыхаю от конференций (т.е. просто работаю), а мои коллеги по сообществу Write the Docs придут. Приходите к ним на стенд с вашими вопросами про документацию.
Если хотите что-то обсудить заранее, приходите с вопросами в чат @docsascode.
Стенд будет выглядеть вот так:
Впереди TeamLeadConf SPb! Пока что я отдыхаю от конференций (т.е. просто работаю), а мои коллеги по сообществу Write the Docs придут. Приходите к ним на стенд с вашими вопросами про документацию.
Если хотите что-то обсудить заранее, приходите с вопросами в чат @docsascode.
Стенд будет выглядеть вот так:
Forwarded from TeamLead Сonf
Есть вопросы по технической документации? Не знаете, какой выбрать инструмент или на кого возложить ответственность за документирование? Спросите на стенде DocOps.