Материал из eSyr's wiki.

Предыдущая лекция | Следующая лекция

Авторский вариант: http://uneex.cs.msu.su/uneex/LecturesDistro2007/08_Heap

Совершенно неожиданно ГК продолжает традицию спонтанных лекций.

[править] О документации

Часть лекции будет в лекционном стиле, часть — в рабочем, будут рассмотрены нерешённые задачи.

[править] Предыстория:

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

Давайте вспомним. как устроена ОС 70-х годов: приезжала машина, и с ней 2 (4) шкафа документации о 8 томах (см. в предыдущих лекциях). Это были массивные труды. Почему так было? Потому что в UNIX-системе царствовал принцип высокооплачеемой работы. UNIX формировался в период холодной войны, и не жалели денег. В частности, им хорошо платили за то, чтобы хорошо писали документацию. Проблема в том, что мы имеем дело не с UNIX, а с Linux, который делается на деньги разумные. Обычно мы имеем дело с человеком, который пишет программы, ибо его легко мотивировать.

[править] Мотивация

[править] Разработчик

Чем может быть мотивирован: прославиться, например. Ради тщеславия, честолюбия. Just for fun. Внедрение (зарабатывает у себя). Заплатили. Повышение квалификации. Люди хорошие, тусовка (социальные связи).

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

Что делают люди, которые пришли в сообщество:

• Поиск ошибок. Ошибки можно имсправлять двояко:
  • Попрыгать-попрыгать и допрыгаться
  • Умозрительно
• Внесение изменений код: заплатки. Деятельное исправление ошибок.
• Новые версии — исправляет новые версии, исправляет ошибки, пришедшие с кодом ДНК автора, приводит её к пакету (идёт перед 3 пунктом)
• Написание кода. Бывает и такое, бывает довольно часто, но по сравнению с другими пунктами не очень.

[править] Что делается в области документации

Тут существует целая куча различий. ГК оставит ещё одно поле и будет туда эти различия вписывать.

• Личностная мотивация. Остаётся, но не так распространена. Зато:
• Просветительская. Есть люди, которые когда что-то знают, они хотят, чтобы все знали это полезное, ибо эти они не знают полезного и им тяжело в жизни. Тем не менее, и пожалуй она наиболее частотная.

• Если человек у себя дома дописывает документацию для зарабатывания себе, то это не так устойчиво. Добавить устойчивости может написание методички. Но вот он не кладёт её никуда. Некая локальная инструкция по использованию того, о чём глобально документация
• С профессиональными навыками совсем плохо. Можно лучше разобаться в системе, попрактиковаться в языке. Преимущество: человек ничего не знал, ему сказали задокументировать, документ ушёл, знания остались.

Но людей, которые мотивированы разработческими мотивациями, довольно много, а документационными — довольно мало.

[править] Задачи, которые выполняются документатором

Написание кода не есть самоцельная задача в разработке, а написание документа это самоцельная задача в документировании.

Пользователи, люди, которые работают с продуктом, имеют такую штуку, как upstream, то есть есть ребята. которые заинтересованы с том, чтобы была программа, это ядро. И когда maintainer что-то патчит, он пишет в upstream. Что же касается документатора, то отдельно upstream'a и maintainer'а не будет. Роль upstream сильно снижается.

Ошибки. Роль community увеличивается. Ибо для поиска ошибок в программе надо специально читать код, а документацию всё равно надо читать. Найти ошибку в тексте проще, тем в программном продукте.

Но вот патчи это страшный сон. Ибо в отличие от программного продукта, где мы дописываем и меняем куски программы, цикл работы документа состоит в его написании, а потом переформулировании отдельных вещей.

В документации не только opt in, но и с новым автором надо понянчиться. На самом деле, труд человека, который пакетирует, вовсе не сизифов, ибо камень недалеко скатывается, это такой камень на пружинке, причём пружинка в вершине горы — всё делается практически автоматом. В случае новой версии документа накладывать патчи практически не удаётся. Ибо если человек что-то правит, то он правит глобально. На diff-patch можно поставить крест по одной простой причине: есть задача документооборота, и эта задача решается только в случае, если все разработчики работают в одном и том же формате, и есть инструмент, похожий на diff-patch, который позволяет отчуждать изменения и причуждать их. Не соблюдается главный принцип: единый формат. Например, можно сказать, что работаем в OpenOffice, остальные не с нами. Эта задача — несбыточная затея, ибо текст на ЯП отличается от текста на естественном, ибо ЯП формализован и структурирован, а на естественном изменения не структурированы и делаются по настроению, например, перестановка предложений порядка слов. Вот тут-то работа бывает действительно сизифовой.

Ещё одна проблема: проблема перевода. Есть отдельно тема локализации, поэтому сейчас её касаться не будут. Это тот же самый сизифов труд, но более извращённый.

• Людей, которые могут документировать, гораздо меньше тех, кто может программировать.
• Процесс практически не автоматизирован, поэтому работы больше

Поэтому документация устаревает, на неамерикаском языке устаревает ещё быстрее. Единственное решение — тележка с долларами.

Это должны быть более мотивированные с горящими глазами фанатики.

Эта проблема решалась единственным способом — изыскивались материальные средства.

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

Тем не менее, если нашлось достаточной количество техписателей, то фактически вы решили проблему документооборота за счёт тележки с долларами.

Появляется провал: мы не можем организовать выпуск дистрибутива, пытаясь организовать его силами свободного сообщества.

ГК хочет организовать сообщество документаторов по принципу свободного сообщества. Что для этого нужно (плавно переходим к идейной куче). Перечислим требования к той соцструктуре, которая будет порождать корпус документов:

Документация в альте: aen писал документацию путём хакания кода, а alt doc team организовывали документооборот, они профессионалы, они организуют систему сборки, вы главное пищите в докбуке, а мы вам будем давать развесистые шаблоны. В результате, когда ГК посмотрел на репозиторий, то там лежал текст, который нахакал aen, какая-то методичка и не помнит что.

• opt in. Свобода входа. У этого термина есть два: мы никого не прогоняем, к нам присоединяется любой. кто захочет, но и когда любой, кто написал документ, должен иметь возможноть к нам прийти. Это выливается вот во что: пришёл человек, “я тут написал в Ворде, это важно”. Смотрят, действительно важно. Хорошо, спасибо. Проблема в том, что нужен удобный редактор Докбука, но это неосуществимо. Докбук хорошая система, но она такая только при двух условиях: вы знаете докубук, и будут люди, котрый его будут перелопачивать. Сстема документирования, которая принимала людой формат, такой ГК не видел вообще. Но такой задачи не стоит перед документаторами, перед ними стоит задача публикации документации, и там формат более любой. Ибо если это ворд, то его можно открыть Ооо. В принципе, можно не говорить “ты пишешь в докбуке”. Более того, если формат можно перевести в хтмл, то это будет документация, если в латех, то это будет книжка.
• Эта задача решена. Как выяснилось, нужна площадка для разработки документа. heap.altlinux.org --- место публикации документов.
• Документописатели не очязаны иметь средства совместной разработки у себя. причём это средство двоякое:
  • wiki. Если человек хочет написать документ.ю то ему надо дать простой инструмент, где можно этот документ писать.
  • Система совместной разработки: git (svn, cvs, darcs, ...). Ибо одной достаточно. git откуда взялся --- революция в сизифе --- есть src.rpm, из которого собирается bin.rpm, хочется чтобы у каждого автора был свой репозиторий, и нужен мейкфайл (хватит спека), чтобы его собирать. Ядро линух лежит в git'е. В чём разница: не нужно каждый раз таскать src.rpm, ибо это бывает довольно тяжело Человек нахакал на 10к, это много, но это копейки по сравнению с 10м того, что он хакал. Но если я хочу нахакать что-то чужое, то я делаю git-clone. Если я вхожу в число людей, которым разрещено любые репозитории собирать, то робот смотрит, говорит, что ризработка не интерферирует, права на сборку есть, и собирант от его лица. Потом автор приходит, видит, что человек собрал, делает git pull и собирает уже от себя.
• Публикатор. Чем хорош --- мы говорим “если вы пишите в чём-то, что конвертируется в хтмл, то он при закачаке автоматически публикуется”. Есди документ не конфертируетсЯ, генерируется кукла, где написаноЮ что это за документ и ссылка на файл с описанием того, как смотреть.
  • Окончательная публикация --- в книжку или как документация на сайте. Багзилла е самая лучшая, особенно в плане взаимодействия. Особенно для разработчика.
  • Ошибки. Публикация для вычитки.
• Классификатор.
  • Паспорт документа. Краткое описание, необходимое для того, чтобы его робот собирал и для того, чтобы потом его найти (паспорт документа, что-то вроде спека)
  • поисковый движок (пока не готов)

Речь идёт о том, чтобы создать такую систему, чтобы там аккумулировались документы, и людей не надо было туда затягивать.

• Любой документ, который приезжает в кучу, сразу попадает в Сизиф, и почти наверняка в дистрибутив. И ещё это удобный тесткейс.

[править] Вавилон

Предположим, достигли техсоверщенста, и есть такой движок, такая система, в которой есть множество входных форматов, выходных форматов (хтмл, латех, вики), некоторые входные переводятся в некоторые выходные, есть средства совместной разработки, есть вики. Чего не хватает, чтобы мы по юзабилити могли приблизиться к разраьотке. Не хватает dif-patch. Это возможно, только при идеальной дисциплине. Но мы можем облегчить короткий документооборотный цикл. Да, есть у нас куча выходных форматов. но сдели этих формато есть большой набор поддерживаемых, то есть тех, которые мы можем разбирать, например, wiki. То есть, если написал статью на вики, то мы её можем стянуть, преобразщовать во внутренний фромат и публиковать как удобно. В результате мы принимаем файл, но дополнительно его распарсиваем и храним.

Для этого надо иметь формат общий и ручки для преобразования. Задача неразрешимая, но можно поставить условия: мы не собираемся распарсивать любой хтмл, а только дополнительно специализованный. И мы пишем не любой текст, а документацию, и тут конечное количество тегов разметки. И при соблюдении этих ограничений задача разрешима. Она позволит снять большинство проблем.

Более того, повыщается свобода выхода.

Технологическая часть сделана не вся, программная почти не сделана, но подвижки имеются.