JavaScript Tutorial — на Github

    Всем привет!

    Некоторое время назад, я опубликовал топик об альфа-версии современного учебника 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, буду дополнять.

    — С наилучшими пожеланиями,
    Илья Кантор
    Поделиться публикацией

    Комментарии 15

      0
      Спасибо Вам. Публикация туториалов в открытом виде это хорошая практика, недавно был опубликован туториал по rails 3, аналогично на гитхабе. Надеюсь Вашему примеру многие последуют.
        0
        Читаю второй день ваш туториал, очень нравится. Спасибо!
          0
          Расширение .md намекает на markdown с расширениями?
            +1
            Верно намекает ;) Из Markdown использованы хедеры (с решеткой), ссылки через [...](), **болд**, *италик* и `код`.

            Это сделано для того, чтобы учебник можно как-то смотреть на гитхабе. Да и вообще, удобно.
              0
              Классно, вот бы еще некоторые вещи стандартизировать.
          • НЛО прилетело и опубликовало эту надпись здесь
              0
              Нет, не проще. Эти форматы не позволяют много всего. Например, запускать javascript.
                0
                То есть, как легкий путь — да, человек не cможет увидеть, что он сделал. А так — склонировал и можно просматривать, запускать примеры.
                • НЛО прилетело и опубликовало эту надпись здесь
              0
              Перевести текст на русский не должно составить труда. Он и так на русском.
              Спасибо, кстате, за отличный туториал!
                0
                Yeah, sorry for my not quite native English. I welcome JavaScript-aware grammar nazi.

                Make it better, it's all github and open source.

                — Yours,
                Ilya Kantor
                  0
                  да я бы рад помочь, только вот с языком у меня туго. Сам писать могу, а переводить — вообще нечитаемо получается. Тем более намного лучше когда один человек занимается переводом, я не верю в крауд-перевод )
                0
                Вполне помог бы с переводом, если бы не github. До сих пор не было времени разобраться в том что там к чему. Кстати, а под чем Вы лицензируете сии тексты? CC?
                  0
                  Тексты будут переведены так или иначе. Хотите помочь — помогите. Лицензия CC BY-NC-SA.
                • НЛО прилетело и опубликовало эту надпись здесь

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

                  Самое читаемое