tgoop.com/prog_way_blog/78
Last Update:
Markdown и о документации к коду.
Для разогрева после перерыва начнём с достаточно простой, но интересной темы. Для многих не очевидно что такое markdown, да и вовсе большинство знакомы с ним на основе README.md файлов на гитхабе, например. Но на самом деле это куда более масштабная технология в моём понимании. Если пойти по теории, то Markdown - это очень легкий язык разметки для обычных человеческих текстов. Большинство воспринимают этот язык разметки не слишком серьёзно, что, как мне кажется, немного ошибочно. В моём понимании markdown достоин куда больше внимания, чем многие думают.
Я говорю о нестандартных для многих способах применения. Одна из главных фишек markdown - его легкая транскрипция в другие более сложные языки разметки. А это значит, что ваш размеченный текст может быть легко преобразован в, например, HTML, XML и т.д. (для этого, кстати, есть уже готовые библиотеки почти для всех популярных языков программирования). Всё зависит от ваших задач, но чаще всего даже транскриптор писать самому далеко не обязательно. Также markdown максимально упрощён и даже имеет вокруг себя кучу графических интерфейсов, которые позволят сделать классную разметку даже компьютерному динозавру.
Всё это значит лишь то, что такой простой инструмент может стать классным подспорьем в ведении документации, отчётности, создании контента и почти любой другой работе с текстом.
Один из реально достойных примеров - сайт веб стандартов. Лично для меня было удивлением, что все статьи на сайте - просто отрендеренные markdown файлики из их репозитория с гитхаба. Решение простое, но гениальное и интуитивно понятное. Каждый желающий просто создаёт файл разметки и статья на сайте готова. Любые изменения уже существующих файлов или добавление новых файлов в репозиторий мгновенно отобразятся на сайте. Таким образом, управление контентом не требует никаких изощрений, вложений, лишней работы и, к тому же, централизовано. По сути, из-за markdown, гитхаб - панель управления контентом для вашего сайта.
Но в названии всё же есть о документации. К чему это я? К тому, что существует 1001 инструмент для создания документации на основе markdown. Чего только стоят, например, Swagger и Markmap. Первый позволяет максимально быстро и просто, а что главное - читаемо, создать качественную документациию к любому REST API, а второй позволит визуализировать markdown в виде интерактивного mind map. Если вам не требуется отдельный инструмент для документирования, то пользоваться markdown можно в чистом виде, тот же гитхаб сделает всё за вас и преобразует текст в понятные и красивые файлы.
И реализовать ведь можно действительно всё что угодно:
— управление контентом
— создание отчётности о тестировании
— любая документация
— редакторы разной направленности (переводим разметку в презентации, например)
— заметки
— выведение статистики (преобразование текста в графики)
— и так далее
Простота и лёгкость в изучении - ключевые в этом плане качества. Сконцентрируйтесь на наполнении, а не на мыслях о внешнем виде. Не нужно ничего выдумывать - просто используйте markdown.
Какие-то такие мысли.
#design #useful #web #github
BY progway — программирование, IT
Share with your friend now:
tgoop.com/prog_way_blog/78