Пожалуйста, перестаньте использовать таблицы в Markdown, особенно если они большие и сложные.
В пятницу ко мне подошел @abogdanov37 и показал новую утилиту, которую он разработал. Она генерирует документацию в Markdown на основе .env файла, включая переменные, их значения и комментарии. Я, конечно, поздравил коллегу с успехом и попросил посмотреть на результат. И тут меня ждал шок — таблица в Markdown! Вы только представьте себе это!
Так начался холивар...
С распространением персональных компьютеров научные статьи, а также книги, методические пособия и учебники, обрели новый носитель. Осталась в прошлом печатная машинка и текст с отступами, куда впоследствии аккуратно вставлялись формулы и рисунки от руки. Математические формулы с появлением TeX набирают обычным текстом. Сейчас TeX уже не просто программа верстки, а способ записи формул. Даже если Вам не довелось с ним работать, а подготовка документа ассоциируется с Word, удобным и быстрым способом ввода формулы в WordЧитать полностью »
Открываю VS Code и начинаю набирать статью с самого начала. Но вот незадача — формат маркдауна не совсем совместим с имеющимся форматом Хабра. Получается выхода нет и придётся возвращаться к встроенному редактору Хабра;
Или не придется?
В голову пришла идея написать утилиту, которая конвертирует разные форматы маркдаунов друг в друга, например, из формата GitHub в формат Habr;
Такую программу я в итоге и разработал. Теперь не надо копировать статьи в редактор Хабра, чтобы посмотреть как она выглядит, можно продолжать писать в любимом VS Code;
Хотя я и использую множество плагинов VS Code, но мысли о неэффективном процессе написания статей не исчезли. Раз уж я набираю текст в VS Code, то почему бы сразу не делать коммиты контента в гит-репозиторий?
Это дало бы немало новых возможностей, которыми пользуются программисты: версионирование, бекапы на локальные носители или веб-сервисы, правки от редакторов и пользователей. А еще можно внедрить CD/CI;
В итоге, я написал небольшой гайд для разработчиков, как писать техническую документацию в редакторах, используя мою утилиту. Саму утилиту можно посмотреть в моём репозитории на GitHub;
В июне этого года в небольшом швейцарском городке Рапперсвиле уже в десятый раз прошло мероприятие под названием ZuriHac. В этот раз на нём собрались более пятисот любителей Хаскелля, от новичков до отцов-основателей языка. Хотя организаторы называют это мероприятие хакатоном, всё же оно не является конференцией или хакатоном в классическом смысле. Его формат отличается от традиционных программистских. Мы узнали про ZuriHac по счастливой случайности, поучаствовали в нем, а теперь считаем своим долгом рассказать о необычной находке!
Иногда не только сама документация, но и процесс работы над ней может быть критичным. Например, в случае проектов львиная часть работы связана именно с подготовкой документации, и неправильный процесс может привести к ошибкам и даже к потере информации, а, следовательно, и к потере времени и выгоды. Но даже если эта тема и не является центральной в вашей работе и находится на периферии, то все равно правильный процесс может улучшить качество документа и сэкономить вам время.
Изложенный здесь подход, с примером конкретной реализации, имеет низкий порог вхождения. Технически, уже завтра вы можете начать работать по-новому.
Читать полностью »
Сейчас то время года, когда студенты выбирают себе классы для обучающих навыков. Один из навыков, который будет поощряться, — обучение LaTeX. Другие могут придти к использованию LaTeX по другим причинам: кто-то хочет сверстать книгу; кто-то слышал, что LaTeX может иметь отношение к журналу Digital Humanities; ну и так далее. Я написал это эссе в качестве предварительного введения в LaTeX. Оно не научит вас использовать редактор (я не имею квалификации для этого!), но я попытаюсь популярно объяснить тем, кто ещё не использует LaTeX, для чего именно он нужен. Это поможет им понять, стоит ли LaTeX усилий на его изучение (не говоря уже о том, чтобы просто заставить его работать). Почему такое большое эссе? Потому что многие из евангелистов превратили LaTeX в фетиш и распространяют дезинформацию о его истинных достоинствах. Хочу прояснить ситуацию.
По словам официального сайта, LaTeX — это «высококачественная система набора и вёрстки» и «стандарт де-факто для обмена и публикации научных документов». С этим никто не спорит.
Читать полностью »
На определенном этапе развития программной системы неизбежно возникает задача разработки пользовательской документации. И тут возникает технический вопрос выбора форматов и инструментов разработки документации.
Читать полностью »
Добрый день.
Вот уж, около полгода, наша компания перешла с системы контроля версий SVN на Git. О преимуществах или недостатках я писать не буду, их обсудили не раз. Ребята, которые этим занимались в нашей команде, написали несколько внутренних статей с основными сценариями: создание бранчей, мерджи и т.п.
Но жизнь преподносит свои сюрпризы и выход за основные сценарии всегда обозначался фразой WTF или говоря по русски «я думал Git сделает так, почему он сделал по другому?»
И всё сводилось к тому, что нужно читать документацию по Гиту. (А на чтение документации, всегда нет времени.)
По этому поводу была статья Завершён перевод книги «Pro Git» на хабре.
Но как оказалось, в документацию ещё вносятся изменения. Не часто, но всё же, тут хорошо видно, когда вносились последние.
И возникла идея слепить последний вариант доки…
Читать полностью »
![GTD / [Из песочницы] Личные цели: контроль версий и красивая распечатка одним щелчком](https://www.pvsm.ru/images/8ffdd6742cdb76fefbbe1a0fed5075bf.jpg "GTD / [Из песочницы] Личные цели: контроль версий и красивая распечатка одним щелчком")
Приветствую уважаемое сообщество! Как многие успели заметить, прошлый год давно кончился — успешно??? Чтобы с уверенностью судить об этом каждому лично для себя, полезно обзавестись "системой отчетности". Или, по выражению классика, PAS. В более ранних статьях того же автора приводятся обоснование, пример использования и обсуждение практик. В частности, высказана критика в адрес большинства программных инструментов для планирования (так называемый "hi-tech" самоменеджмента). Основная претензия — нехватка гибкости. В этом, преимущество за "mid-tech" и "low-tech" средствами (notepad, карандаш и бумага, пластиковые файлы и байндеры на кольцах — продолжитеЧитать полностью »
