В каком формате было бы удобнее написать мини-учебник по Kohana v3.2?
- Отдельный pdf-файл (удобно читать в оффлайне) (52%, 57 голосов)
- Userguide (MarkDown-файлы, просмотр через браузер на сайте или локально) (40%, 44 голосов)
- Просто циклом статей в блоге (можно комментировать) (26%, 28 голосов)
- Свой вариант (предложу в комментариях) (3%, 3 голосов)
Всего голосовавших: 109
Loading ...Если вкратце, то у меня есть мысли (и даже желание) составить мини-учебник для начинающих, что-то вроде Kohana 101 (был такой PDF-файл для Kohana 2.3, если помните). Пока что не особо принципиально, в чем его писать. Есть некоторые аргументы в пользу одной или другой версии:
1. Поддержание в актуальном состоянии. Естественно, в случае с PDF это сложнее.
2. Обратная связь с пользователями. Статьи в блоге можно комментировать, это плюс.
3. Версионность. Документацию на текстовых файлах можно выложить на Github и собирать поправки от других пользователей.
4. Удобство пользованием. Что ни говори, а PDF-файл можно распечатать, его удобно читать с различных ридеров и т.д. В блоге больше лишних (отвлекающих) элементов.
Продолжать можно долго. А что думаете вы? Помимо формата, принимаются предложения по содержанию учебника.
pdf-файл неудобно читать с ридеров. На всем, что меньше 9″ — pdf читается с мучениями.
Имхо, первый вариант рулит. Дополнять можно через гитхаб. Обратную связь можно держать в одном посте на этом блоге, вряд ли будет особо большая движуха.
Hi, I think that userguide is very nice tool and it’s the best format to create any tutorials or documentation. In second place I would use blog.
Sorry for english, but I’m from Poland and i haven’t got russian keyboard.
Markdown удобен тем, что можно и блог скинуть с форматированием и в pdf и как-то мобильный формат вроде epub.
https://github.com/progit/progit обратите внимание на этот проект. Здесь пишут весьма успешно книгу с использованием markdown и есть несколько сборщиков для различных форматов.
Авторы книги «Pro Git» нашли компромиссный вариант — сама книга лежит в репозитории на github.com/progit/progit/ в формате Markdown (удобно читать через сам github, связь с пользователем в той, или иной мере поддерживается через Issues), а в корне репозитория лежит ruby-скрипт, который собирает книгу в «твердый» формат по требованию.
А когда будут первые плоды?
Скорее всего не в этом году. Пока что времени мало. Первые наброски я уже сделал, но выкладывать их рано.