Comments 40
Не знал, что документация пишется в markdown-формате. Думал, что это только короткие readme и мануальчики.
Ни дня без открытий) Вот целая лекция про его возможности https://habr.com/ru/company/yandex/blog/342192/
Единственный вопрос - а зачем? Старый добрый Word не катит? Зачем поддержка LaTeX, например?
как тебе удобно в word историю изменений смотреть ?
а статик сайт (html) документаци сделать ?
latex требует высокого порога вхождения, я попробовал, сделал, но возвращаться нет желания
потому выбираю markdown на текущий момент
Хм... Ну, пожалуй...
DOCX документ заливается в Git, соответственно история изменений смотрится через любой diff-инструмент, который вы используете с Git, и который поддерживает DOCX.
Я использую Git Extesions (с винды). Он поддерживает сравнение и DOCX и PDF из коробки.
Так неудобно же в ворде. Особенно при Docs as code.
Тут такое дело.
Как верно заметили ниже - историю изменений не посмотреть, это раз. Второе - вставить кусок кода, чтобы это не было тошнотворно.
И вообще, зависит от задачи.
P.S.
Была несколько лет назад халтура - "собрать" из нескольких сотен вордовых текстов и картинок из Bizagi альбом формата А3. У каждого из исполнителей (большей частью почтенные дамы и, без ёрничанья, действительно специалисты) было "Своё Представление О Прекрасном" (с) в смысле оформления документов. Заказчику нужно было красиво для "Предоставления Куда Надо" (с) ;)
За рабочую неделю "слепил" конвеййер, который
1) "разбирал" тексты по параграфам и темам (шапка, краткое описание, формальное наполнение, нормативные ссылки, ссылка на картинку из Bizagi). Питоном и башем "разбирал", "складывал" в CSV.
2) При помощи не-помню-уже-какого "кликера" запускал этот адовый Bizagi (на отельной машине, в виртуалке он не жил) и "заставлял" его экспортировать диаграмму в SVG (а не PNG).
3) Написал и отладил в LaTeX шаблоны для титульной страницы, оглавления (номера страниц были с пропусками, типа, после 200 легко могло быть и 210) и содержательной части. Соственно, основная часть затраченного времени и ушла на изучение этого чудесного продукта.
Не могу представить, как это можно было бы сделать в любом ворд-процессоре.
М-да, поглотили воспоминания, а то, ради чего начал излагать всё это, так и не написал. ;)
Короче.
Любой инструмент он для своих задач. Использовать ворд-процессор для документации - явный перебор. Всякие нарядные свистелки просто мешают. А возможность "играться" шрифтами/цветами/форматированием в любом месте документа - безусловное зло.
"Плоский" текст же таких вольностей не позволяет. Форматирование в Markdown-редакторах (в известных мне, по крайней мере) тупо "приколочено гвоздями" к экрану. Если совсем невмоготу - меняй тему (а это .CSS практически везде). Немногим это необходимо и ещё меньшее количество способно это сделать без ошибок (я - не могу, ибо не надо ;) ). И это хорошо.
Далее.
С "плоским" же текстом легко работать. Даже с таблицами markdown и вставками кода, т.к. это просто текст. Можно весь процесс на bash написать и это будет работать и работать хорошо.
Конечно же есть масса библиотек и тулов, которые из почти любого формата вытащат содержимое и позволят либо использовать его либо сослаться на него. Но зачем так сложно?
Справедливости ради — в word встроено как сравнение двух (версий) документов, так и сохранение истории изменений внутри самого документа с авторами, аппрувом или отклонением изменений и т.п. Из какого-нибудь vscode код вставляется в той же подсветке и «теме» и шрифте, что был в самом редакторе — результат гораздо предсказуемее, чем попытки распарсить неполный код сторонним раскрашивателем.
А если бы почтенные дамы в markdown или latex претворили бы каждая своё видение прекрасного? — например, ссылки как код, списки бы и заголовки через эмидзи оформили бы — вы бы markdown и latex забраковали?
Word и (la)tex — системы семантической разметки текста: можно разметить заранее согласованными стилями/классами термины, имена файлов, клавиатурные сочетания и затем «лёгким движением руки» получить глоссарий терминов, файлов, справочник по комбинациям клавиш, общий список авторов и т.п. Да, это требует некоторой прилежности от всех участников и связано с другими попоболями, но в итоге из набора word/latex документов реально собрать единую документацию с перекрёстными ссылками и прочими прелестями. "Плоский" текст же таких вольностей не позволяет.
Хм, а ведь определенно должно уже что-то существовать для поддержи LaTeX'а в VS Code… А я об этом раньше и не думал.
GitHub Markdown Preview
Начиная с версии 1.63 добавлено автообновление для открытых страниц встроенного просмотрщика. Просмотр Ctrl+Shift+V
Rainbow bracket
Начиная с версии 1.60 определяется настройкой
"editor.bracketPairColorization.enabled": true,
Попробовала и MdTableEditor, и Markdown All in One и еще несколько не упомянутых в статье расширений, а так и не могу найти вариант для объединения столбцов в таблице (не строк).
Автор, если сталкивались, подскажите
Толкового решения до сих пор так и нет https://stackoverflow.com/questions/46621765/can-i-merge-table-rows-in-markdown
А насколько SettingsSync сейчас актуален, учитывая возможность синхронизации настроек «из коробки»?
если вы на разных машинах и системах работаете одновременно
@Tony-Solимел в виду, что это встроенная функция VSCode. И уже несколько лет. :)
Что же вы за несколько лет документацию не прочли?
Is VS Code Settings Sync the same as the Settings Sync extension?
No, the Settings Sync extension by Shan Khan uses a private Gist on GitHub to share your VS Code settings across different machines and is unrelated to the VS Code Settings Sync.
разница только в том, что там гист, а нативный синк - сервера майкрософта) поэтому всё верно. Давно отказался от Settings Sync, встроенный синкает всё, и разницы в осях нет. Ну или можно делать настройки для конкретной оси, например, terminal.integrated.profiles.linux и terminal.integrated.profiles.osx, и тп
Документацию к расширению перестал читать с выхода нативной функции синхронизации, собственно потому и спрашивал, что может есть какой-нибудь крутой функционал в плагине, которого нет в нативной синхронизации.
У вас ряд расширений выполняет то же самое, например, prettier, Markdownlint и MD all in one. Вы их как альтернативы указываете или есть отличия?
Есть отличия, есть разница в удобстве и личные вкусы, сделать сравнительный обзор цели не было. Зато можно поставить все, смотреть как работает и выкидывать ненужное постепенно.
Я, например, выкинула Prettier, любимый миллионами. Мне он показался излишеством. Но не указать его в подборке я просто не могла себе позволить. Мой коллега техпис без него жить не может.
да, согласен полностью) тоже выбросил. Он и на фронтенде уже не нужен, т.к. stylelint и eslint в разы более гибкие в настройке и имеют свои форматтеры
Ну вот да. Задача была у текста глобальная — дать понять, что для разработки документации всем этим можно пользоваться, как и VS Code в целом. Передо мной в ежедневной рутине достаточно наглядно представлен массивный срез российских техписов, и мало кто из них пользуется всеми этими инструментами. Предпочитают разрабатывать доку в Confluence и в Word.
В прошлом посте меня попросили написать про расширения для разработки доки, я написала этот текст еще и поэтому). На русском мало подобных функциональных подборок для технических писателей индексируется поисковиками.
Rainbow bracket да, уже тоже отметили, что не акутален.
Rainbow Bracket -> Rainbow Brackets
Оно ж давно не обновлялось
И в его аналоге написано, что это уже поддерживается из коробки
https://marketplace.visualstudio.com/items?itemName=CoenraadS.bracket-pair-colorizer-2
Не первый коммент) https://habr.com/ru/post/698702/comments/#comment_24903694
28 расширений VS Code для разработки документации