Всем привет!
Некоторое время назад, я опубликовал топик об альфа-версии современного учебника JavaScript, пока на английском: javascript.info.
В комментариях были высказаны пожелания, в частности:
В репозитарии github.com/iliakan/javascript-book находится альфа-верисия уже offline и open-source JavaScript книги, которую можно читать хоть на островах Кука без интернета. И все интерактивные примеры будут работать.
Также можно редактировать ее и присылать обновления, а в частности — переводить.
Хотелось бы поделиться мыслями, почему для развития учебника был принят именно Github.
Очевидный вариант для совместного редактирования — это вики. В данном случае вики не подходит, т.к. учебник должен быть концептуально целостным.
Это не пачка независимых страниц энциклопедии, а последовательное изложение. То есть, нужен редактор, который держит в уме всю картину, принимает и мержит изменения.
Может быть несколько редакторов, если учебник содержит несколько независимых разделов.
Следующая идея — сделать систему совместного редактирования, удовлетворяющую требованиям, которые написаны выше.
Эдакое совместное редактирование документации с основной веткой, в которую мержит только основной редактор и редакторы разделов. Это достаточно просто, все необходимые компоненты для таких систем есть.
Однако, особенность учебника в том, что должно быть много примеров HTML/JS/CSS. Желательно, интерактивных. А их удобно писать и тестировать именно оффлайн, на диске — ну никак не онлайн.
В качестве итогового варианта выбран Git-репозитарий и оффлайн-версия учебника, включая все скрипты, примеры, картинки и т.п.
Сложность такого подхода — для редактирования желательно знание Git (для чтения — можно просто архив скачать).
Как минимум, установка Git, чтобы склонировать, а затем делать
Плюсы — видно, кто что прислал, обсуждение на Github, issues, pull requests — вся инфраструктура.
Основная техническая сложность создания оффлайн-варианта была в том, что книгу надо не только выложить, а еще дать возможность локально просматривать, редактировать и видеть изменения.
Форматирование текста книги — это сложный парсер, гораздо сложнее обычных markdown, rdoc, textile etc. В основном, это из-за подключения интерактивных примеров. Кроме того, есть дополнительные фичи оформления, например, специальное выделение, авто-оглавление и другие. К этому формату я шел некоторое время, и он удобен.
Чтобы дать возможность видеть красивую, полностью рабочую страницу, форматирование было переписано на чистый JS. При этом для подгрузки и подсветки примеров используется локальный XmlHttpRequest + пропатченный Syntaxhighlighter. Версия 3 хайлайтера не умеет врапить строки текста, поэтому версия 2.
Если есть мысли, почему лучше перейти на 3 — буду рад выслушать.
То есть, вьювер загружает соответствующий файл, парсит, подгружает что надо и выводит. Всего примерно полторы тысячи строк кода, и некоторое время на то, чтобы все это закодить.
Единственное исключение — JS не умеет ходить по директориям, поэтому для перегенерации навигации используется подписанный Java Applet. Он запускается только при выборе соответствующего действия. А можно и не перегенерировать навигацию. Апплет достаточно безопасен, его исходники находятся там же.
Сейчас open-source учебник можно скачать, просматривать, редактировать и присылать изменения/перевод на Github github.com/iliakan/javascript-book.
Пишите, если появятся какие-то вопросы или предложения… Да, кстати, там есть readme, буду дополнять.
— С наилучшими пожеланиями,
Илья Кантор
Некоторое время назад, я опубликовал топик об альфа-версии современного учебника JavaScript, пока на английском: javascript.info.
В комментариях были высказаны пожелания, в частности:
- Выложить исходники книги в open source.
- Сделать оффлайн-версию.
- Сделать возможность совместной работы над книгой на Github.
В репозитарии github.com/iliakan/javascript-book находится альфа-верисия уже offline и open-source JavaScript книги, которую можно читать хоть на островах Кука без интернета. И все интерактивные примеры будут работать.
Также можно редактировать ее и присылать обновления, а в частности — переводить.
Хотелось бы поделиться мыслями, почему для развития учебника был принят именно Github.
Вики
Очевидный вариант для совместного редактирования — это вики. В данном случае вики не подходит, т.к. учебник должен быть концептуально целостным.
Это не пачка независимых страниц энциклопедии, а последовательное изложение. То есть, нужен редактор, который держит в уме всю картину, принимает и мержит изменения.
Может быть несколько редакторов, если учебник содержит несколько независимых разделов.
Своя онлайн-система
Следующая идея — сделать систему совместного редактирования, удовлетворяющую требованиям, которые написаны выше.
Эдакое совместное редактирование документации с основной веткой, в которую мержит только основной редактор и редакторы разделов. Это достаточно просто, все необходимые компоненты для таких систем есть.
Однако, особенность учебника в том, что должно быть много примеров HTML/JS/CSS. Желательно, интерактивных. А их удобно писать и тестировать именно оффлайн, на диске — ну никак не онлайн.
Итоговый вариант
В качестве итогового варианта выбран Git-репозитарий и оффлайн-версия учебника, включая все скрипты, примеры, картинки и т.п.
Сложность такого подхода — для редактирования желательно знание Git (для чтения — можно просто архив скачать).
Как минимум, установка Git, чтобы склонировать, а затем делать
git diff
и присылать изменения. А лучше — полноценное знание для pull requests. Это повышает порог входа для редакторов.Плюсы — видно, кто что прислал, обсуждение на Github, issues, pull requests — вся инфраструктура.
Основная техническая сложность создания оффлайн-варианта была в том, что книгу надо не только выложить, а еще дать возможность локально просматривать, редактировать и видеть изменения.
Форматирование текста книги — это сложный парсер, гораздо сложнее обычных markdown, rdoc, textile etc. В основном, это из-за подключения интерактивных примеров. Кроме того, есть дополнительные фичи оформления, например, специальное выделение, авто-оглавление и другие. К этому формату я шел некоторое время, и он удобен.
Чтобы дать возможность видеть красивую, полностью рабочую страницу, форматирование было переписано на чистый JS. При этом для подгрузки и подсветки примеров используется локальный XmlHttpRequest + пропатченный Syntaxhighlighter. Версия 3 хайлайтера не умеет врапить строки текста, поэтому версия 2.
Если есть мысли, почему лучше перейти на 3 — буду рад выслушать.
То есть, вьювер загружает соответствующий файл, парсит, подгружает что надо и выводит. Всего примерно полторы тысячи строк кода, и некоторое время на то, чтобы все это закодить.
Единственное исключение — JS не умеет ходить по директориям, поэтому для перегенерации навигации используется подписанный Java Applet. Он запускается только при выборе соответствующего действия. А можно и не перегенерировать навигацию. Апплет достаточно безопасен, его исходники находятся там же.
Сейчас open-source учебник можно скачать, просматривать, редактировать и присылать изменения/перевод на Github github.com/iliakan/javascript-book.
Пишите, если появятся какие-то вопросы или предложения… Да, кстати, там есть readme, буду дополнять.
— С наилучшими пожеланиями,
Илья Кантор