Здравствуйте, velkin, Вы писали:

V>Тема для одноимённого опроса по предпочитаемому формату документации для того, чтобы каждый мог не только проголосовать, но и прокомментировать почему он предпочитает то или другое.

Обсуждаются крайности — это раз (оптимум может лежать посередине), не определена многостраничная — два (что есть страница?). Также зависит от типа документа, использования. В одном случае может быть хорошо то, в другом — это.

Один из минусов многостраничной — дополнительное форматирование, отсюда чаще встречаются неудобства (до развала форматирования или выскакивания неудобных скроллбаров) при изменении размера окна или масштабировании содержимого. Другой минус — дополнительные кнопки листания страниц или переключение с мыши на клавиатуру — неудобная или ненужная суета. При обилии графики или ветвистых формул возникают "вдовы" и "сироты", контент искусственно разделяется на страницы, что оправданно в бумажной печати, но глупо сейчас.

В многостраничном, казалось бы, удобней ставить ссылки (для себя), но на практике часто бывает ровно наоборот.

Мой оптимум — это разбиение на одностраничные главы + средство поиска по всему. Многие документы часто просматриваю по диагонали и вверх-вниз. Многостраничные считаю хренью и тяжелым наследием прошлого без преимуществ, если не рассматривать художественную или бюрократическую литературу.

Здравствуйте, goto, Вы писали:

G>Обсуждаются крайности — это раз (оптимум может лежать посередине), не определена многостраничная — два (что есть страница?). Также зависит от типа документа, использования. В одном случае может быть хорошо то, в другом — это.

Одностраничная это когда всего одна страница. Всё что больше одной страницы это многостраничная, то есть это две или более страницы. Понятно, что можно объединять множество страниц в более крупные страницы, но это всё равно многостраничная документация с точки зрения текущего обсуждения. Даже если разбить документацию на две страницы, то вылезают все те плюсы и минусы о которых я написал в топике. А может что-то ещё, что я забыл или не предусмотрел.

Тема про то до какой степени объединять многостраничную документацию тоже интересна. Когда остановить объединение, когда охвачено какое-то понятие или просто по главам. Или напротив пытаться всё разбить чуть ли не до абзацев и предложений, раз уж пошла такая тема для опытов. Но в данном случае документация рассматривается целиком вне зависимости от того какого она размера и может ли текущий компьютер её открыть (загрузить), разобрать (распарсить) и отобразить.

Обсуждаются ключевые подходы, а не возможности или потребности. Не задаются вопросы вроде где кончается одна документация и начинается другая. Если брать конкретные примеры, то заходишь на сайт какого-нибудь проекта, а там предлагают скачать документ или смотреть документацию прямо в онлайне.

Тот же один файл pdf со всей документацией внутри можно условно считать одностраничной документацией, потому что там есть страницы, но это физические страницы для печати, а не логические страницы оглавления, но самое главное не нужно переоткрывать кучу файлов. А если это html и его производные, то это как раз наш случай, так как можно создать одну большую html страницу, а можно много небольших. И не важно подкачиваются они в онлайне или уже скачаны в офлайн.

Потому на твой вопрос, что есть страница я отвечу, что это именно логическая страница связанная с оглавлением, а не физическая страница, которая в электронных документах является пережитком физических носителей. Текущее обсуждение про электронные документы и логические страницы оглавления. Но если кто-то для чего-то поделит документ на физические страницы создав множество файлов страниц, то это будет многостраничная документация. Документация состоящая из двух и более pdf файлов это тоже многостраничная документация.

Ключевые признаки я тоже описал. Если можно запустить поиск по странице, то есть нажать Ctrl+F и найти по тексту всё что угодно, перематывать всю документацию полосой прокрутки, не переходить на другую страницу при редактировании данных, то всё это признаки одностраничной документации. В противном же случае это многостраничная документация. Я думаю, что людям при голосовании не нужны столь обширные пояснения, вроде и так понятно к чему этот опрос.

По идее специальный софт мог бы.
1. Открывать множество файлов документации как один.
2. Разбивать один файл на множество независимых окон редактора.

Но тогда бы опрос сменился бы на то какое представление документации вы предпочитаете, одностраничное или многостраничное. Основная суть вопроса при этом бы не изменилась. Взять тот же chm (compiled html), важно ведь не то, что там один файл снаружи, а то что представление зависит от количества скомпилированных файлов html внутри. В него можно поместить как одностраничную, так и многостраничную документацию. И разница проявится прежде всего в представлении документации, а не в количестве внешних файлов.

В общем я сейчас больше занимаюсь болтологией, что может не только разъяснить, но и запутать, а опрос такой какой есть. Объяснение для совсем уж самых маленьких и запутавшихся, что одностраничная документация та, которую можно целиком промотать колёсиком мышки, а ту для которой нет перемотки и надо обязательно щёлкать левой кнопкой мыши по ссылкам чтобы перейти на другие страницы можно считать многостраничной.

Здравствуйте, velkin, Вы писали:

V>В общем я сейчас больше занимаюсь болтологией, что может не только разъяснить, но и запутать, а опрос такой какой есть. Объяснение для совсем уж самых маленьких и запутавшихся, что одностраничная документация та, которую можно целиком промотать колёсиком мышки, а ту для которой нет перемотки и надо обязательно щёлкать левой кнопкой мыши по ссылкам чтобы перейти на другие страницы можно считать многостраничной.

Все это стоило определить перед опросом. Теперь результаты опроса можно выбросить, т.к. вводные некоторыми были поняты не так, и уже ничего не вернешь.

Если в начале я увидел крайности, то с уточнениями вообще не понимаю, что там обсуждать. Кажется размытым и беспредметным, что ли. В чем проблема-то?

Здравствуйте, goto, Вы писали:

G>Все это стоило определить перед опросом. Теперь результаты опроса можно выбросить, т.к. вводные некоторыми были поняты не так, и уже ничего не вернешь.

Всё нормально, некоторые голосовали прямо со страницы опросника ещё до создания данной темы. Мне какая-то особая точность не требуется. И даже если кто-то ошибётся в понимании тоже ничего страшного не произойдёт.

G>Если в начале я увидел крайности, то с уточнениями вообще не понимаю, что там обсуждать. Кажется размытым и беспредметным, что ли. В чем проблема-то?

Зачем я создал этот опрос? Чего я хочу этим добиться?



В общем может кто видел, что я начал вести личную базу знаний и даже создал несколько тем в блогах по ним. Я даже Obsidian недавно проверил, не только Zim на предмет пригодности.

Но произошло буквально следующее, я включил идущие в составе Zim плагины.
1. Обратные ссылки.
2. Метки.
3. Вложения.

И я обнаружил, что.
1. Благодаря обратным ссылкам некоторые вспомогательные ссылки в содержимом мне больше не нужны.
2. Метки они же теги позволяют уменьшить названия за счёт того, что служат дополнительными уточнениями, которые уже не нужно делать в самом названии.
3. А вложения позволили мне осознать, что ими проще управлять, если документация одностраничная.

Причём окно вложений может сворачиваться, на скриншоте ниже я его развернул.



Смысл в том, что тот же Qt слишком обширен для сворачивание документации в одну страницу, но это можно сделать для каждого класса, то есть не разбивать его на члены. Это можно частично сделать для примеров кода или для целых программ.

В принципе для любых не бьющихся понятий встаёт выбор.
1. Или одностраничная документация с автоматически создаваемым по заголовкам "Оглавление" справа, это видно на скриншоте.
2. Или подстраницы со ссылками, тогда переход будет осуществляться с помощью "Содержание" слева, это тоже видно на скриншоте.

А я ещё помню ходил по сайтам, и чаще документация была многостраничной, но изредка попадалась одностраничная и лично для меня она была удобнее в использовании. Я или проматывал страницу или искал поиском по ней же. А оглавление работало также, что и с многостраничной документацией, только перематывало по странице, а не перебрасывало на другую.

Создав данную тему я.
1. Сформулировал отличия видов документаций.
2. Получаю статистику по предпочтениям других людей.
3. Получаю дополнительные мысли в чужих комментариях.

Пока что люди склоняют меня к одностраничной документации с оглавлением (панель справа), нежели к многостраничной с содержанием (панель слева). В принципе многостраничную я уже пробовал, не всегда это хорошо. А полноценную большую одностраничную ещё не создавал.

Не знаю как другим, а мне пока что формулировка темы, сам опрос и комментарии к нему кажутся очень полезными. Понятно, что полезность для других людей не гарантирована, да и далеко не всем это интересно. Но для меня опрос имеет практический смысл.

Здравствуйте, velkin, Вы писали:

V>Возможно у кого-то есть ещё свои аргументы в пользу того или иного варианта. Вопрос в том, что вы предпочитаете и почему?

одна страница, но качественно структурирована. С оглавлением.
Из-за удобности поиска.

"Многостраничная" требует вникания в ее структуру, лишнее время тратится на поиск.

Здравствуйте, velkin, Вы писали:

Texinfo позволяет генерировать оба варианта из одного источника

А вообще в 99% случаях важнее адекватность понимаю того, кто будет читать. А вот с этим у программистов обычно катастрофический напряг.

На днях нас форсированно засадили слушать лекцию по одному Очень Важному Компоненту. Она затянулась на два часа, из которых один час ушёл на то, как Главный Эксперт с кашей во рту, как у многих нейтивов, объяснял банальности по презенташке, а ещё час компания из 10 человек рассказывала абсолютно несущественную историю разработки, перемежая шутками, так что они больше смеялись, чем рассказывали. Суммарно пользы 0 целых хрен десятых и два потерянных часа жизни у каждого из ~50 обязанных присутствовать.
Считаю это образцом, как не надо делать.

Здравствуйте, velkin, Вы писали:

V>Тема для одноимённого опроса по предпочитаемому формату документации для того, чтобы каждый мог не только проголосовать, но и прокомментировать почему он предпочитает то или другое.

Смотря сколько печатных страниц в этой документации, пять или 500.

Здравствуйте, velkin, Вы писали:


Некоторые пользователи любят распечатать и читать с бумаги
Самое оптимальное для документации это правильно приготовленный pdf

Здравствуйте, velkin, Вы писали:

V>Возможно у кого-то есть ещё свои аргументы в пользу того или иного варианта. Вопрос в том, что вы предпочитаете и почему?

0-страничную. Это когда и без документации всё понятно.

Здравствуйте, velkin, Вы писали:

V>Возможно у кого-то есть ещё свои аргументы в пользу того или иного варианта. Вопрос в том, что вы предпочитаете и почему?

Одностраничная: удобнее делать поиск по словам.