Эталонным решением считается "монография" - это такой текст, в котором
1) мысли упорядочены согласно единому плану (оглавление),
2) подтверждены фактами
3) содержат ссылки на сторонние источники для уточнения, проверки и учёта авторских прав
сейчас подобные работы принято оформлять в виде .pdf-файлов,
так как
1) там получается чёткая раскладка на страницы;
2) их не очень удобно редактировать, то есть создаётся иллюзия "релиза";
3) формат распространён и про него знают библиотеки, например киберленинка.
Существуют альтернативные стандарты, такие как .epub3. Там удобнее формирование из HTML, но с распространённостью хуже.

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

В монографиях могут встречаться (содержание):
- терминологические словари (иногда развёрнуто, иногда в качестве индекса - какие слова на каких страницах смотреть);
- список иллюстраций (его иногда хотят видеть высокие руководители, чтобы посмотреть картинки);
- другие приложения.

Можно ли сделать такой массив текста удобным для использования? Для этого есть несколько технологий:
1) гиперссылки между частями текста (они могут иметь печатное отражение, например "см. параграф N в разделе MMM")
2) поиск по ключевым словам
3) поиск по контексту (если дело происходит в IDE, а документ является справкой по работе с IDE)
мне очень жаль, что не развилась идея о справке вида "нажал на элемент пользовательского интерфейса -> получил по нему справку, как было с windows и .hlp-файлами.

Если выкладывать текст на сайте, то можно разбивать его на логические блоки, но нужно это делать как-то так, чтобы блоки не стали слишком мелкими. Пример - законы России в системе consultant могут просматриваться постатейно, но это неудобно для беглого поиска по всему документу. Поэтому там есть отдельно режим просмотра всего документа.

Почему одни интернет-учебники читаются лучше чем другие? Потому что их части более правильно пролинкованы. Разные читатели имеют разные пробелы в знаниях и у них должна быть возможность чтения в нужном конкретно им порядке. С другой стороны (несмотря на единый принцип пролинкованности), викиучебники отделились от википедии, потому что это разные жанры текста (энциклопедия и тексты-прохождения процедур (walkthrough tutorials)).

Хотелось бы иметь унифицированную (в смысле объединённую) технологию для описания текстов программ. Такая технология должна поддерживаться:
1) рантаймом и библиотеками UI (чтобы работал вызов контекстной справки, надо чтобы у элементов пользовательского интерфейса были идентификаторы);
2) редактором кода (чтобы можно было дописывать справку одновременно с редактированием кода, однако, чтобы код не замусоривался документацией, как это происходит в случае XML-комментариев;
3) сайтом (чтобы документацию можно было просматривать через web, и желательно редактировать в wiki-режиме)
4) системой публикации, чтобы можно было из массивов фрагментов сформировать упорядоченный .pdf-текст для релиза в библиотеки
в создании pdf при помощи Libra Office Write есть недостаток - исходные фрагменты текста не связаны с git. Поэтому хотелось бы иметь утилиту, которая берёт с git пролинкованные между собой фрагменты гипертекста и формирует из этой каши и плана (конфига) финальный .pdf. Это позволило бы иметь возможность видеть по git кто и какие изменения вносил в текст.

Хорошо бы ещё, чтобы можно было внедрять в сам документ цепочку электронных подписей (это с точки зрения релизов и аппрувов). А то в git подписи есть, а вот как может быть подписан .pdf внутренними средствами (а не отдельным файлом с чексуммами и отпечатками) - мне неизвестно.

Отредактировано Лис (2017-04-03 15:08:45)