Новый фид для гайдов и списков на JSON — зачем нужен и как может выглядеть на примере чеклиста
Придумал простой и понятный аналог RSS-фида и формата синдикации Atom, но для чеклистов и иного контента с последовательной структурой.
TL;DR
Взял опубликованный ранее на vc.ru гайд и вместе с коллегами переработал его в интерактивный чеклист. На его примере показываю первую версию фида для структурированного контента [инструкций, чеклистов и так далее].
Далее в двух словах объясняю, что к чему, предлагаю покритиковать идею и обсудить в комментариях планы по дальнейшему развитию проекта.
Зачем он нужен
Руководства, гайды и туториалы не пишет только ленивый. Ими делятся компании, онлайн-школы, вузы и даже госструктуры.
Это оправдано и продуктивно: текст в виде последовательности действий, списка вещей или моментов, на которые стоит обратить внимание, обещает читателю минимум «воды» и максимум пользы. Однако находить такие материалы в потоке всего, что выходит в соцсетях и медиа — сложно.
Заголовок «Как настроить ИТ-инфраструктуру в облаке» не обязательно означает, что внутри вас ждет чеклист. Но даже если в нем будет пометка вроде «N шагов для», текст может содержать лишь пространные рассуждения автора на тему и не обладать последовательной структурой.
В итоге аудитория не может в полной мере пользоваться преимуществами такого контента, а у авторов нет мотивации для его подготовки и борьбы за внимание читателя. На этом круг, казалось бы, замыкается.
Но разобраться с поиском и синдикацией подобных материалов все-таки можно. Например, если дать авторам инструмент для их структурирования и публикации на собственных сайтах, а разработчикам — протокол для написания кастомных ридеров [вроде тех, что позволяют подписываться на блоги и подкасты с помощью RSS и некоторых его аналогов].
Так аудитория сможет получать чеклисты и гайды напрямую, выбирать ридер по своим потребностям и решать, какие материалы читать, а какие [с помощью ридера] автоматически исключать из своей подборки.
Что в первой версии
Реализовать такой проект скорее всего можно на основе существующих форматов синдикации — RSS, Atom, JSON Feed и других. Первые два построены на языке разметки XML. Он универсален; плюс у него есть обширная экосистема вспомогательных решений. Однако RSS и Atom фактически заморожены и не получают обновлений десятилетиями. Работать с ними [читать фид с листа «as is» и редактировать XML-разметку] сложно даже тем, кто годами занимается блогами, контентом и запускает свои подкасты.
Поэтому несколько лет назад и появился JSON Feed. Сформировать ленту по его спецификации на JSON смогут даже те, кто на пушечный выстрел не подходил к программированию. Для JSON Feed есть конвертеры из RSS, валидаторы для проверки ленты и другие полезные инструменты. Формат используют не так массово, как RSS и Atom, но заметные примеры вроде NPR, Daring Fireball и у некоторых русскоязычных авторов все-таки есть.
Однако — на мой взгляд — спецификация JSON Feed обладает скромными возможностями для структурирования содержимого публикаций. Ее авторы просто-напросто не ставили перед собой такую задачу и не занимались вопросом выделения того или иного типа материалов из общей массы публикаций в сети. Поэтому делать надстройку, состоящую на 95% из кастомных тегов, я не стал, и вместо этого предложил новый узкоспециализированный формат структурированного контента.
Для этого я взял готовый гайд, опубликованный ранее на vc.ru. Вместе с коллегами пересобрал его в отдельную страничку с минималистичной анимацией и отредактировал содержание. После этого — описал получившийся чеклист в виде ленты на JSON. Для краткости показываю, как выглядит пример фида для первого подраздела этого чеклиста:
Как вы можете видеть, теги говорят сами за себя, поэтому описывать каждый из них не буду. Отмечу только, что тут есть структура на случай, если организация поделится несколькими материалами [lists] и посчитает нужным задать подразделы [chapters] — например, для длинных чеклистов.
Еще здесь исключена html-разметка из текстовых описаний подразделов и пунктов [statements]. Так у компаний будет меньше возможностей для развешивания рекламных ссылок, и читатель не будет отвлекаться на ненужные рефы. Инструменты [tools], на которые обычно и дают ссылки, — вынесены в отдельную категорию. В веб-версии чеклиста этот элемент находится под текстом и сейчас выглядит вот так:
Если говорить о смысловом дроблении, пока остановился на описании [description], условии выполнения [condition] и дисклеймере [disclaimer]. Последние два тега — опциональные, как и некоторые другие — вроде [tools].
Что предстоит доработать
Опыта в разработке протоколов и стандартов для обмена данными у меня нет, а на первую версию я потратил буквально несколько вечеров. Поэтому правки могут быть существенные по мере того, как я буду анализировать обратную связь и аналоги [помимо RSS, Atom и JSON Feed есть огромное количество других форматов, поэтому мой — может претерпеть много изменений].
Подумаю о расширении количества опциональных тегов. Например, с данными об организации и авторах материалов. Плюс — о том, каким образом рекомендовать оформление тега "host_description" [думаю, что здесь стоит дать зеленый свет для размещения ссылок на кейсы, как тут].
Еще постараюсь подготовить больше примеров того, как можно структурировать другие типы контента с помощью этого формата.
Конечно же, хочется думать и о разработке фидбернера, валидатора и ридера, но до всего этого еще нужно дойти, запастись терпением и ресурсами.
проблема в целом понятна, но больно уж узкая кмк
к тому же разработать формат не проблема, проблема чтобы его начал хоть кто-то использовать - чаще всего стандарты выходят из крупных компаний
плюс стандарт подразумевает детальную спецификацию, тут пока её не увидел
Тут иная ситуация: 3-4 попсовых протокола синдикации контента, поэтому есть, где разгуляться. Если серьезно, идея не в конкуренции с ними, а в специализации, как завещали, например, разработчики RSS «Subsequent work should happen… in completely new syndication formats, with new names» [ в конце дока тут https://cyber.harvard.edu/rss/rss.html#roadmap ]
Да, задачка с внедрением есть. Но с чего-то нужно начинать, поэтому решил обсудить на примере, как только сделал его, а потом уже развивать и документировать. Описать теги и докрутить дополнительные будет не так и сложно даже без помощи корпораций. Хотя если появится интерес со стороны компаний или иных организаций, точно будет веселее, да и с внедрением попроще.
С таким материалом и уровнем проработки вам лучше на Хабрахабр
Хорошо, напишу. Но и тут буду продолжать рассказывать, как только будет прогресс
Никогда не любил json из-за беспрецедентно большого количества кавычек, которые нужно ещё и экранировать.
Да, есть такое. Какую альтернативу вы могли бы предложить?
Protobuf
У протобуфа есть одна маленькая особенность. И имя ей - схема данных, без которой не распарить эти самые данные. Завтра изменится структура и вот у тебя еще проблема похуже кавычек: 2 схемы данных, которые ещё нужно уметь различать, корректно парсить/мигрировать, а под капотом в твоей модели все равно ровно по этой причине будет обьект с кучей нуллабл полей, либо отдельный монструозный мигратор версий.
Спасибо, изучу. Даже на вики-страничке у него есть интересные рефы на Apache Avro, например
Протобуф имеет смысл вообще внутри компании между микросервисами обмениваться данными единой модели.
Просто не держать в каждом микросервисе слой модели, а иметь общий.
Но тут тоже есть минусы - поле одной и той же сущности может быть в одном микросервисе nullable, a в другом required.
У технологии стоимость входа гораздо выше, чем у жсон:)
Какие там скобочки.. человеку http 2 нужно знать минимум.
У вас классная затея имхо нужно смотреть в сторону cms как некий плагин для автоматического структурирования howto статей.
Плюс формата, что он ещё автора ограничивает и не даёт возможность лишнего писать.
Но вам как разработчику нужно попробовать разные под разные категории howto подогнать свой стандарт, появятся какие-то специфичные поля.
Если сравнить рецепт готовки еды и настройку какой-то Linux утилиты.
Спасибо, постараюсь так и сделать!
Могу предложить json-lite. Суть её заключается в том, что переменные не заключены в кавычки, тем самым мы уменьшаем их в 2 раза)
К сожалению этот стандарт только в моей голове.
Хорошо, тогда пока с кавычками повозимся
Json как средство передачи информации самое лучшее что придумали пока. Мне нравятся ещё конфиги в nginx. Легко и просто выглядят.
yaml
Так ли он понятен будет нетехнарям?
А чем он сложнее json ? Текстовый, а букв писать меньше.
Технорям должен зайти protobuf. Он бинарный, что положительно сказывается на размере, быстро парсится. Но если хочешь посмотреть глазами, то надо приседать. В общем, отлично заходит для хайлоада.
Если у тебя не хайлоад, то выбирай любой текстовый на свой вкус: xml, json, yaml, ... наверное что-то ещё.
YAML, а если добавить автоматизацию через pandoc , то это покрывает все форматы pdf, MD, latex bibtex docx и ТД ИТП 23 тысячи 🌟 на гитхабе.
YAML
Комментарий удален модератором
Комментарий удален модератором
Почему бы и нет