Комментарии 7
А зачем?
Очень плохо.
Если вкратце: все придуманное удобно для автора, но абсолютно неудобно и бессмысленно для пользователя.
Во-первых, эти ваши деревянные спойлеры сильно мешают воспринимать информацию. Я понимаю, что автору так удобнее: что в голову пришло, то и написал, а потом что показалось лишним — упрятал в удобненький инлайн-спойлер. Но для читателя разбирать такое безобразие — пытка:
— в отличие от обычного спойлера, нет никаких намеков на то, что содержится внутри. У спойлера хотя бы заголовочек бывает, здесь — просто эллипсис {...}. Еще и не выделяющийся на фоне остального текста.
— вложенные «древоспойлеры» лично меня бесят. Наверное, потому, что для читателя «древоспойлеры» очень похожи на сноски в конце книги, т.е. там вроде как дополнительная информация, для получения которой надо открыть книгу в конце и поискать нужную сноску (в нашем случае — навестись мышой на эллипсис и потом заново навестись глазами на поехавший текст). Но когда в тексте сноски идет еще одна сноска — это уже немножко бесяче.
Во-вторых, из-за этих спойлеров информация тупо не видна. Для сайта с документацией это очень-очень странно. Поиск поломан, структуры никакой нет, снаружи на содержимое спойлера никак не сошлешься.
Ожидается, что документация будет построена структурированно, по принципу «сначала кратенько об основном, потом подробненько разбор в деталях, в конце — всякие баги-глюки-закавыки». Да, это требует времени и сил. Зато пользоваться такой документацией удобно, в отличие от неструктурированной кучи скрытых вложенных примечаний.
Теперь собственно о самом YearVer. Схема, опять-таки, удобна для автора (думать не надо), но бессмысленна для пользователя.
Обычная практика версионирования — это major.minor.patch, причем желательно с возможностью легкой сортировки и сравнения. Изменение major части версии обычно означает, что в продукт внесены фичи, несовместимые с предыдущими версиями (например, в библиотеке поменялось ABI, в игре — формат сохранения сейвов и т.п.). По minor и patch частям версии пользователь может прикинуть, какая версия свежее и много ли в ней изменилось (например, если изменился только номер patch, то версии отличаются подфикшенными багами, а если вырос номер minor — ну, небось иконки покрасивше сделали.
У вас же major часть будет меняться каждый год, minor — каждый месяц (или вообще каждый новый билд). Т.е. для пользователя схема версионирования становится максимально непрозрачной: чем отличается 2021.11.1 от 2022.1.1? Получится ли просто обновить версию и работать дальше, или версии обратно несовместимы и придется апгрейдиться по полной?
А еще будут проблемы с сортировкой: лексикографическая сортировка плохо работает с датами без ведущих нулей. Будет примерно такое:
2021.1.1
2021.11.1
2021.12.1
2021.2.1
Если вкратце: все придуманное удобно для автора, но абсолютно неудобно и бессмысленно для пользователя.
Отвечу также вкратце: это дело привычки.
вложенные «древоспойлеры» лично меня бесят.… Но когда в тексте сноски идет еще одна сноска — это уже немножко бесяче.
Тут отчасти я с вами согласен. Сайт yearver.org в этом отношении является некоторым экспериментом, так как и я обычно стараюсь ограничиваться одним уровнем вложенности (как например тут (см. запись от 2017.11.22 10:03:36) или тут).
Поиск поломан, структуры никакой нет, снаружи на содержимое спойлера никак не сошлешься
Поиск и ссылки на древотекст сделать теоретически возможно (хотя и довольно сложно), но у меня лично при работе с документацией к 11l проблем с этим никогда не возникало.
Ожидается, что документация будет построена структурированно, по принципу «сначала кратенько об основном, потом подробненько разбор в деталях, в конце — всякие баги-глюки-закавыки».
Интересный тезис. А можете привести какой-нибудь реальный пример такой образцовой документации?
Теперь собственно о самом YearVer. Схема, опять-таки, удобна для автора (думать не надо), но бессмысленна для пользователя.
Простите за нескромный вопрос — а вы сами занимались разработкой ПО более или менее профессионально? Тогда разработкой какого ПО, если не секрет? [Я, если что, никакого секрета из своего профессионального опыта не делаю (вкратце он изложен на моей домашней странице).]
в игре — формат сохранения сейвов
Можете привести хоть один пример "увеличения major части версии" в играх? Если появляется вторая часть какой-то игры, то это уже просто другая/новая игра [как правило с полностью несовместимыми сейвами], а не новая версия старой игры. В обновлениях же игр формат хранения сейвов обычно не меняется, а если и меняется, то сейвы всех старых версий всегда поддерживаются в более новых версиях.
Остальные ваши рассуждения в пользу обычной практики версионирования семантического версионирования комментировать не вижу смысла, достаточно привести такой факт, что некоторые крупные компании переводят свои проекты с семантического версионирования на календарное (в том числе YearVer), например JetBrains (IntelliJ IDEA, PyCharm, CLion и пр.) и Unity.
А на основе моего личного опыта я могу сказать, что календарное версионирование (и в частности YearVer) подходит лучше, чем семантическое, практически для всех проектов, в которых я принимал участие.
Однако для подключаемых библиотек уже не годится, там важнее видеть не «свежесть», а совместимость. Пакеты в npm и packagist использую семантическое версионирование, и номер версии здесь играет большую роль в определении совместимости пакета с вашим окружением разработки.
А можете привести какой-нибудь реальный пример такой образцовой документации?
Образцовой — нет. А достаточно удобной — да.
Например, Linux Man Pages. Учитывая примитивную технологию, но которой они реализованы — вполне себе хорошечно. Любая страница — это кратенькое описание команды (synopsys), затем более подробный разбор всего и вся (description). И в конце всякое дополнительное знание (caveats, bugs, etc).
Собственно, по тому же образцу построена документация много где. Тот же РНР, например.
Простите за нескромный вопрос — а вы сами занимались разработкой ПО более или менее профессионально? Тогда разработкой какого ПО, если не секрет?
Почему занимался? Я и сейчас занимаюсь. Уже двадцать лет всякое пишу — в основном для серверов.
А на основе моего личного опыта я могу сказать, что календарное версионирование (и в частности YearVer) подходит лучше, чем семантическое, практически для всех проектов, в которых я принимал участие.
Ключевое слово — «я».
А в проектах, на которых работал я, практически всегда использовалось семантическое версионирование. Причем неспроста — пользователям надо было знать, смогут они обновиться на новую версию малой кровью или придется неделями конфиги править. Но это не значит, что я считаю такое версионирование чем-то особенно полезным.
Новая технология письменности («древопись») на примере сайта YearVer